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Creativity is more than just being different... 
Anybody can play weird — that's easy. 
What's hard is to be as simple as Bach. 

Malcing the simple complicated is commonplace 
Making the complicated simple — - 
awesomely simple; 

That's creativity. 

— Charles Mingus, jazz musician ( 1 922- 1 979) 



The MacFORTH project is dedicated to Alexander Ramsay, 
and proudly bears the Ramsay tartan on its cover. In his 
90th year, he is a continuing source of inspiration for the 
road ahead. 
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Introduction 

To 
MacFORTH™ 



WELCOME! We are about to make your work more fun. We'll do it by making 
you more productive with results that are easier to attain. The Apple 
Macintosh'" (or more fondly 'Mac') represents a revolution in the way that 
users interface to computers. Few computer users who have experienced the 
Mac's graphics, windows, menus, or mouse will happily choose to go back to 
the same old alpha screen and keyboard interface. 

In order to provide a consistent user interface across all applications, Apple 
has included a large amount of software features in read-only memory (ROM) 
built into every Macintosh. MacFORTH has been specifically tailored to put 
these functions at your disposal. 

Regardless of your prior programming experience, you will find writing 
programs for the Macintosh to be a new and exciting experience. The 
objective of this manual and the MacFORTH product is to equip you with the 
necessary tools to develop software which fits comfortably within the 
Macintosh environment. 

Learning how to effectively use the Macintosh is in many ways similar to 
learning FORTH. Each is based on extensions to a small set of simple 
concepts. Each requires you to re-orient the way you approach computer 
related applications, and allows you to get better results with less effort. 

In order to learn how to use the Macintosh , we will first teach you how to 
write programs in MacFORTH, and then how to use such programs to interface 
to the Macintosh. 
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We have included a Computer Aided Instruction Course for those just 
beginning to learn FORTH. The course is designed to help novice FORTH users 
and programmers to understand how to solve problems with MacFORTH. If you 
are an old hand at FORTH, you'll want to go quickly through the course to 
review some of the basics of MacFORTH. 



Creative Solutions has been producing 68000 based FORTH systems since 
1979. The MacFORTH product is a derivative of our Multi-FORTH'" product 
line, specifically tuned to take maximum advantage of the Macintosh features 
and facilities. 



CSI 68000 FORTH Products have been used to solve problems across a wide 
spectrum of applications: 

Airborne Radar Systems 

Telephone Company Circuit Analyzers 

General Accounting Systems 

Video Games 

Nuclear Power Plant Pipe Testers 

Spread Sheet Programs 

Data Base Managers 

Hospital Operating Room Patient Monitoring 

and some of the world's largest ROBOTS 
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The MacFORTH product line is divided into three areas: 

Level I 

For the hobbyist or those just getting started with the Macintosh. The Level 1 
product has been designed to put the tremendous power of the Macintosh at 
your fingertips, without your having to l<now a lot about programming or 
computers. This and all levels of the MacFORTH product line provide 
stand-alone programming capabilities with the Mac, as well as TRACE, DEBUG, 
and toolbox access. Support of the serial interface and sound capabilities of 
the Mac is also Included. 



Level 



For the Professional who will be using MacFORTH in her/his work. The Level 2 
product includes many enhancements such as more advanced graphics 
commands, a full 68000 in-line assembler, floating point, and more 
documentation allowing further access to the toolbox, it is specifically 
designed to meet the needs of the professional user. 



Level II 



For program developers thinking of either converting existing programs to run 
on the Mac or developing new programs. Level 3 will allow you to do all of 
your program development on the Mac, and then generate run-time only 
versions of your product (contact CSI for details on royalties and other 
arrangements). This version includes support from CSI, additional 
documentation and 250 "right to execute" licenses. 
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The Macintosh: An Appliance Computer 

The Macintosh is intended to be the first mass-marl<et personal computer. It 
is designed to appeal to an audience of non-programmers, including people 
who have traditionally feared and distrusted computers. To achieve this goal, 
the Macintosh must be friendly. The system must dispel any notion that 
computers are difficult to use. Two key ingredients combine in making a 
system easy to use: familiarity and consistency. 

Familiarity means the user easily understands and is comfortable with what 
is expected of her or him at all times. Most Macintosh applications are 
oriented towards common tasks: writing, graphics and paste-up work, ledger 
sheet arithmetic, chart and graph preparation, and sorting and filing. The 
actual environment for performing these tasks already exists in people's 
offices and homes; we mimic that environment to an extent which makes 
users comfortable with the system. Extensive use of graphics plays an 
important part in the creation of a familiar and intuitive environment. 

Consistency means a uniform way of approaching tasks across applications. 
For example, when users learn how to insert text into a document, or how to 
select a column of figures in one application, they should be able to take that 
knowledge with them into other applications and build upon it. Uniformity and 
consistency in the user interface reduces frustration and makes a user more 
at ease with the task at hand. 

Years of software development, testing, and research have gone into the 
definition of the Macintosh user interface. On many other computers, since 
little or no user interface aids are built in, each applications programmer 
invents a new and original interface for each program. This leads to many 
different (and usually conflicting) interfaces. 

Apple has attempted to avoid this situation on Macintosh by building tools for 
a versatile, well-tested user interface and placing them in ROM to be used by 
all application programs. There's no strict requirement that an applications 
program must use any or all of the supplied interface tools; but programmers 
who create their own interface do so at the expense of their own development 
time, useable data space, and the overall consistency of the application. 

MacFORTH is able to directly access most of the built-in tool box functions. 
Since the toolbox has been designed for general applicability, often the 
amount of set-up required to perform even a simple function (like adding a 
window or menu item) is extensive. We have factored out the most common 
functions (menu, window, mouse, and file operations) and provided you with 
simplified FORTH operators which make them easy to use. 



Introduction Page i-9 June 3, 1984 



MacFORTH: 

A High Performance, Interactive Programming Environment 

FORTH Is a language, but it Is also a tallorable operating system and a set of 
tools for developing and debugging your programs Interactively. Since FORTH 
is all of these things at once, it has been accurately described as a 
"programming environment". 

We feel that FORTH matches the process of human thought more closely than 
any other programming method. Defining your own commands as you go along, 
and using these commands in defining further commands, you actually create 
your own personalized programming environment that is natural to the way 
you think about your applications. 

FORTH gives you as much or as little control over the computer hardware as 
you want, at any level — from the most powerful application commands down 
to the machine code instructions. Figure 1 illustrates the various levels at 
which comparable programming languages operate. 

MacFORTH is a very powerful 32-bit implementation of FORTH which includes 
the traditional features of FORTH as well as many new innovations. 

Philosophically, FORTH takes a substantially different approach to developing 
computer applications from other languages and operating systems. Most 
other programming systems were designed to teach students how to solve 
simple, self-contained problems on large timesharing or batch mainframe 
computers. FORTH was developed specifically by and for the use of scientific 
and engineering professionals in the solution of difficult real time data 
acquisition and process automation problems. Since its inception over ten 
years ago, FORTH has been hammered into its current form on the hard anvil of 
actual applications experience. What has emerged is a system which 
anticipates competence and technical responsibility by the user and in turn, 
delivers unbridled performance. 

MacFORTH puts the power of the computer In your hands. If you choose to 
execute an endless loop or overwrite your program with data, MacFORTH will 
not stand in your way. Consider the analogy of a power saw. The saw 
substantially reduces the time required to cut a piece of wood to a desired 
size. It does not protect you however, from cutting in half the sawhorse on 
which the board rests. Avoiding such an obvious error is your responsibility. 
Consider the cost of a saw which was able to detect sawhorses and turned 
itself off whenever it encountered one ~ similar to the tremendous overhead 
involved in many "traditional" computer languages. 
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While using MacFORTH, you will occasionally cause an error which will 
require a restart of the system. This is the natural result of the learning 
process. As you become more proficient, this will occur less frequently. 
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Iterative Organization 

The organization of this manual is cyclic/ not linear. Before we elaborate, 
let's look at the method most often used for designing FORTH applications. 

The oldest programming approach was simply to write code until you finished. 
Later the fashion was to organize a program into "modules", then to code each 
of the modules. This approach was named "top down design", and the older 
approach was dubbed "bottom up". 

FORTH uses a still newer approach. Modularization is part of the method, but 
the "modules" (or sl<eletal versions of the modules) are actually coded and 
tested at the same time they are designed. You can code a "sketch" of the 
applications, and test to see if your general solution to the problem is 
correct. If not, you simply rewrite the simple outline, and continue testing 
until you're satisfied. Then you can "flesh out" the outline with more detail. 

This process is called "iterative development." On each iteration you solve 
the problem at a deeper level and gather information necessary to avoid 
problems at the next lower level. If you reach a point where insufficient 
information is available, it is easy to interactively explore alternative 
approaches, selecting the best solution at that level. 

We have utilized a similar approach in this manual. The manual is divided 
Into two main sections: the User's Guide and the Reference Guide. The 
beginning chapters of the User's Guide show you to how to interact with 
MacFORTH: creating, editing and saving. Later chapters of the User's Guide 
walk you through successively more comprehensive examples, building on 
previously developed skills and introducing the MacFORTH interface to each of 
the major Macintosh features and facilities. The Graphics Results chapter 
introduces graphics, and how to use the extensive set of graphics tools built 
into the Macintosh. 

The User's Guide ends with an example which touches on the major functions 
highlighted by a separate chapter In the Reference Guide. 

The Reference Guide provides in-depth discussion of the MacFORTH interface 
to each of the following Macintosh features: Menus, Windows, File System, 
and Printing/Serial Interface. 

The Reference Guide also discusses Advanced Topics, Error Handling, and 
provides a glossary of all user applicable words in the system. 
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We hope our approach makes learning MacFORTH easy. We know you'll be happy 
with the results. 



Creative Solutions solicits any comments in reference to the form, content, 
or accuracy of this manual. Your responses will allow this documentation to 
evolve to better meet the needs of our customers. Please send your comments 
to: 

MacFORTH Product Manager 
Creative Solutions, Inc. 
4701 Randolph Road, Suite 12 
Rockville,MD 20852 
301-984-0262 
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Chapter 1: installation 



Overview 

This chapter wil] show you how to install MacFORTH'" on your computer. It 
will also discuss the files found on your MacFORTH system disk. 



License Agreement 

Before opening the package which contains the MacFORTH System Disc, 
carefully read the License Agreement on the cover of the package. Briefly, It 
states . . . 

MacFORTH, including this manual and supplied diskette and contents of 
both, Is owned exclusively by Creative Solutions, Inc. A copyright Is 
registered with the United States Copyright Office, for both the manual 
and the accompanying object code. After paying the license fee, 
agreeing to the terms of the license agreement, and returning the 
attached registration card, you are licensed to use MacFORTH on a 
single computer system. 

You may not provide copies of CSI supplied materials to anyone else for 
any reason. If you transfer your right to use MacFORTH to anyone else, 
you are then no longer licensed to use it yourself. 

We're quite serious about this. The MacFORTH product is the result of an 
enormous amount of work. We have foregone any hardware copy protection 
scheme for your convenience, we simply encode a serial number on each disk. 
This allows you to always have a backup In the event of a media or hardware 
failure and allows us to trace the source of illegal copies. We feel that we 
have produced an outstanding product for the price, and that our customers 
will respect our efforts and the law by adhering to these terms. If the cover 
to the manual that you are reading does not include the distinctive MacFORTH 
red, white and black logo, you are utilizing a copy which was produced in 
violation of US copyright laws. Contact your attorney for instructions on how 
to return this Illegally produced material to Creative Solutions. 

Be sure you make a backup of your MacFORTH system disk 
before you use the system! 
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Making a Backup 

Be sure to write protect your original MacFORTH clisl< before you make a 
backup. This is described in your Macintosh System documentation (on page 89 
- "Locked Disks"). 

Place the MacFORTH disc in your drive and follow the instructions in your 
Macintosh System documentation (on page 81 - "Copying an Entire Disk"). 

When you have made a backup, store the original disk in a safe place and use 
your backup disk. This will protect you in the event of a disc related error. 



Loading MacFORTH 

Before you just start experimenting with the system, you should proceed 
through this manual, trying each example (feel free to try other examples of 
your own on the topic being presented). This may sound a little harsh, but the 
Macintosh is like no other computer. There are many unique features you need 
to know about to make the best use of this new computer. 

When you are ready to load MacFORTH, place the MacFORTH system disk in the 
drive and reset your computer (either press the programmer's reset button, or 
turn the computer off, then back on). 

Loading the MacFORTH Svstem 

To load the MacFORTH system (which loads MacFORTH and the editor), double 
click on either the "MacFORTH 1.1" icon or the "FORTH Blocks" Icon. "FORTH 
Blocks" is a MacFORTH document and will load the MacFORTH sytem first, then 
load the source code contained in the "FORTH Blocks" file itself. 

The MacFORTH window will appear and you will see the soon-to-be-familiar 
"ok". The arrow cursor will turn into a wristwatch, indicating you should 
wait while the system is extended to include the editor (you will notice that 
when source code is loaded from disk, the cursor will turn into a wristwatch 
temporarily). Finally, you will be asked to enter your initials (this Is for the 
editor and is explained in more detail in the "Program Editing" chapter). 



Loading Only MacFORTH 

If you want to load the MacFORTH system itself, without the editor or any 
other "extras", edit block 1 of the "FORTH Blocks" file and delete (or comment 
out) any commands which load other code. 
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Setting MacFORTH as the "Startup" File 

Finder 1.1 (the current level of the Macintosh operating system) allows you to 
select a file to be automatically loaded when the computer is reset (or turned 
on). To select MacFORTH as the auto-load file, from the Finder, select the 
"MacFORTH 1.1" icon (it will become inverted), and then select the "Set 
Startup" item from the "Special" menu. To verify that MacFORTH will be 
automatically loaded, turn your computer off then on and watch MacFORTH 
load. 



Loading the MacFORTH Demos 

In order to understand the demos better, we highly recommend that you 

complete the Users Guide section of this manual (chapters 1 through 6). 

The demos provide a few graphic and music examples for your amusement. To 
load the demos from the Finder, double click on the "Demo Blocks" file. To 
load the demos from MacFORTH, execute the phrase 
mCLUDE- Demo Blocks' 

The demos provided are: 

1.) Approach 

Spins in the MacFORTH logo. Shows the rotation and scaling features 

of the MacFORTH graphics package. 
2.) Clock 

Displays the current time (as read from the internal clock) in the 

format of an analog clock. Shows real time update of the window. 

You can change the size of the clock by resizing its window. 

3.) Dark Beams 

Displays a series of lines which can create some facinating results. 
Try resizing the window. 

4) Bouncer 

Displays a bouncing ball in the window. Resize the window for 
different bouncing patterns. 

5.) Spirals 

Displays some geometric doodling. Shows the speed and power of the 
MacFORTH graphics package. The code for this demo fits easily in one 
block of source code. 

6.) Sound 

Plays Bach's two part invention *8. 
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To select the demo you like, activate its window (by clicking the mouse down 
inside its window) or pull down the music menu. You can see (and modify if 
you like) the source code for the demos by simply editing the "Demo Blocks" 
file (as described in the Program Editing chapter). 

We provide the source code to the demos for you to use as examples. Feel free 
to modify the code for the purpose of experimentation. We discuss how to do 
this in the Editing chapter. 



Contents of the MacFORTH System Disk 

In case you're wondering what each of the files on the disc are: 

1.) "MacFORTH 1.1" 

Contains the MacFORTH system itself. When opened from the Finder 
(by double-clicking), it loads MacFORTH, and then the "FORTH Blocks" 
file to extend the system. (By "extending" the MacFORTH system, you 
are simply loading the standard utilities ~ and any you might add to 
the load block for the "FORTH Blocks" file.) 

2.) "FORTH Blocks" 

MacFORTH blocks file which contains the source code for some useful 
utilities. It is loaded to extend the MacFORTH system. Modify block 
one of this file if you want to load your application automatically 
when MacFORTH is loaded. 

3.) "Going FORTH" 

MacFORTH blocks file which contains the source code for the Going 
FORTH tutorial. Double-click on this file to load the computer-aided 
instruction course. 

4) "GF Data- 
Contains the text used in the Going FORTH tutorial. 

5.) "Demo Blocks" 

MacFORTH blocks file which contains the source code for the demos. 

6.) "MacFORTH Folder" 

A Mac folder used to hold files used by MacFORTH. The Finder and 
system are contained in this folder to avoid cluttering up the screen. 
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MacFORTH Customer Support Hotline: (301) 984-3530 

We have established the "MacFORTH Hotline" to assist you with questions 
and/or problems you have concerning the MacFORTH product. Help is available 
between the hours of 1 p.m. and 5 p.m. EST, Monday thru Friday (excluding 
holidays) at (30 1)984-3530. 

The following guidelines have been established for the MacFORTH Hotline: 

I.) Only MacFORTH customers who have signed and returned their 
registration cards may use the MacFORTH hotline. If you haven't 
signed and returned your card (the one attached to the disk envelope) 
yet, do it now. 

2.) Know your serial number (its on the original MacFORTH disk you 
received). You need to tell the person answering the hotline your 
name and disk number before you can ask your questions. 

3.) Have your questions written down in front of you. We allow a 
maximum of 5 minutes per call when others are waiting. This is 
ample time to answer even a long list of questions if they are clear 
and written down. 

4.) Please don't use the hotline for marketing questions. This is for 
technical support only . 

If these quidelines seem a bit harsh, please understand. We are happy to 
support valid, registered users who have questions about MacFORTH. 

You can also direct any questions/comments/suggestions in writing to: 
MacFORTH Product Manager 
Creative Solutions, Inc. 
4701 Randolph Road, Suite 12 
Rockville, MD 20878 
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Overview 

This chapter provides the instructions for running the Going FORTH computer 
aided instruction course which is supplied on the MacFORTH system disc. 

The tutorial is designed for everyone. The novice FORTH programmer will 
learn the basics of FORTH, more experienced FORTH programmers will get a 
flavor for running MacFORTH on the Macintosh. 

It is Important that you run through the course, as many Macintosh specific 
terms are introduced there. We will assume you have run the course and use 
these terms throughout the manual. 



Preparation 

To run the course, power up your Macintosh with the MacFORTH system disc in 
the drive. Open the "Going FORTH" document (by double clicking in it). While 
it is loading, you will get the message "Loading the Going FORTH Tutorial." Be 
sure you read this chapter before you begin the course (and remember to 
re-size the window). 

Once the course is loaded, you need to shrink the size of the MacFORTH 
window by dragging its size box over to the left. Figure 2.1 shows what your 
screen should look like while running Going FORTH. 



Running the Course 

When you uncover the Going FORTH window, the course will start 
automatically, displaying the first frame. On the right hand side of the 
window you will notice the scroll bar. To move on to the next frame, click 
the arrow In the lower right side of the window. To review previous 
material, click the arrow in the upper right side of the window. 

To move from chapter to chapter, click the mouse down In the shaded area 
above or below the scroll box (the scroll box Is the white box in the shaded 
area of the scroll bar). You can also move the scroll box to any position 
within the course by dragging the scroll box up or down. 

If you press any keys while in the Going FORTH window, the Mac will beep at 
you, reminding you that you can only enter keystrokes in the MacFORTH 
window while you are completing the tutorial. 
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If you close the Going FORTH window, you can re-enter the course by selecting 
the "Going FORTH" item from the "Tutorial" menu. 

That's it! That's all you need to know; the tutorial will give you any 
additional instructions you need, now get going FORTH! 
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Overview 

This chapter introduces you to one of the most used features of (iacFORTH, 
the editor. Using the editor, you can create and save your programs on disc. 
This allows you to create and modify program source code without retyping it 
each time you load the system. The liacFORTH editor uses an editing 
technique similar to MacWrite, so If you are familiar with MacWrite, you will 
be right at home using the HacFORTH editor. 

The MacFORTH editor is used to edit program source files on the disc. We will 
introduce some of the file system commands you will use normally with the 
editor. For an in-depth discussion of the file system and its commands, refer 
to the File System chapter. 



Preparation 

To start this session load the MacFORTH system by resetting your Macintosh 
(power off then on or press programmers reset button on the left side of your 
machine) . With your MacFORTH disc in the drive, double click on either the 
"MacFORTH 1.1" or the "FORTH Blocks" file in the window that appears on your 
screen (if you have set the MacFORTH file as the startup file, you don't need to 
double click on the "MacFORTH 1.1" Icon). When this file loads, It also loads 
the editor from the file "Editor Blocks" automatically. (Remember to enter 
your initials when asked.) 

We'll stress again the Importance of the editor to your effectiveness with 
MacFORTH and urge you to spend the time now to understand how it works. 
You should try each example In this chapter before continuing with the 
manual. 

Be sure to restart your computer as instructed above so that the examples In 
this chapter make sense. 



Selecting a File for Editing 

When you loaded the "FORTH Blocks" file from the Finder (If you don't know 
what the finder is, refer to your Macintosh manuals), MacFORTH assigned the 
file to file number 0, opened It and selected It as the current "blocks file". 
The MacFORTH editor allows you to edit the current "blocks file" only. (File 
assignment, opening, selection and file numbers are discussed in more detail 
in the File System chapter. For now, just execute the examples to practice 
using the editor.) 
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Displaying File Assignments 

You can see what files are assigned and opened by executing: 
7FILES 

You can see that "FORTH Blocks" is assigned to file number 0, that it is open 
(by the capital "0"), and that it is the current "blocks file" (by the capital "B" 
~ this is explained in more detail in the File System chapter). 

Since the "FORTH Blocks" file is the file you are going to work with in this 
chapter, you don't need to do anything else to continue. For your reference, we 
will discuss how to select a different file for editing. 

Using a Different File to Edit 

If you want to use a different file for editing, execute the USE" command in 

the following format: 

USE" <file naie>" 

USE" assigns the file specified by the name <fi1e name> to the first available 
file number, opens it, and selects it as the current blocks file for editing (if 
it is a blocks file). For example, if you wanted to edit the source code for the 
MacFORTH demos (contained in the file "Demo Blocks"), you would execute 
( don't execute this example now): 
USE" Deio Blocks" 



Selecting a Different File to Edit 

Once a file has been assigned and opened (via the USE" command, for 
example), you simply select it as the file to edit with the SELECT command. 
SELECT is used in the following format: 
<file nuaber> SELECT 

So, for example, if you wanted to edit the program source code contained in 
the file assigned to file number 1 (assuming it is a blocks file), you would 
execute ( don't execute this example now): 
1 SELECT 

SELECT acts on a file which has already been assigned a number. USE" should 
be used when that file has not yet had a number assigned to it (e.g. the first 
time you use the file after entering MacFORTH ). 
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Entering the Editor 

There are three ways to enter the editor (don't try any of these techniques 
just yet, simply become familiar with how to enter the editor); 
1.) Execute the EDIT command in the following format: 
<block«> EDIT 

ie; ( don't try this example now) 
5 EDIT 

2.) Activate the editor window by clicking in it with the mouse. 

3.) Pull down the "Edit" menu and select the "Enter Edit" item 
(or execute its equivalent keystroke, command E). 



Exiting the Editor 

There are three ways to exit the editor (don't try any of these techniques just 
yet, simply become familiar with how to exit the editor): 

1) Pull down the "Edit" menu and select "Exit Editor" item (or 
execute its equivalent keystroke, command E) . 

2) Click in another window with the mouse. 

3) Close the editor window by clicking in its close box. 



Block Buffers 

When a block is edited, it is read from disk into memory. The area of memory 
it is kept in during the editing process is called a "block buffer". Each time a 
change is made to the block, it is modified in the block buffer only. When you 
exit the editor, or select another block to edit the block is written to disk. 

Once again, the image of the block you are editing is in memory and not 
updated (written) to the file on disk until you exit the editor or select 
another block to edit. 
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Usjng the Editor 

The files you will edit are called "block files" because they are made up of a 
sequence of "blocks" (old-time FORTH programmers may prefer the term 
"screens"). A block Is the fundamental unit of disc storage used by MacFORTH. 
It is simply a fixed length record containing 1024 characters for programs. 
The "FORTH Blocks" file on the MacFORTH system disc contains the source 
code for some MacFORTH utilities, as well as empty space for your use. 

You should organize your program source code logically Into files by 
categories. For example, you can see that we put the MacFORTH utilities in 
the "FORTH Blocks" file, the demo programs in the "Demo Blocks" file, and the 
Going FORTH tutorial source code in the "Going FORTH" file. By logically 
organizing your source code into files you will find program development 
simplified greatly. 



Practice Editing Block 

In order to illustrate the use of the editor, we have provided a practice block 
for you to work with while completing this chapter. Begin by displaying the 
practice block with the editor. Execute 
5 EDIT 

You should now see on your screen an edit window which looks like figure 3.1 
below: 



Blk# 5 of 23 ; Flle=Forth Blocks 



( Sample Editing Practice Block ) 

CR ," Loading Editor Practice Block.." 

; .PLUS ( nl\n2 — I add n1 to n2 and display the result ) 
CR OUER , ."plus " DUP . + ." equals " . ,; 

CR ." Editor Practice Block Loaded." 



O 



B 



Figure 3.1 
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Editor Window 

The liacFORTH editor uses its own window. The window is large enough to 
display one block of source code in a format16 lines by 64 characters each for 
a total of 1024 characters (as you can see in Figure 3.1). The following list 
points out the features of the editor (don't try these features just yet, simply 
read through the list to familiarize yourself with each): 

- Title Bar 

Displays the current block number being edited, the total number of 
blocks in the file and the file name. Each time you edit a different 
block this information is updated to show you exactly what you are 
editing. 

- Close Box 

Lets you close the editor window by clicking in its close box. The 
editor window will reappear the next time you enter the editor. 

- Drag Region 

Allows you to drag the edit window to a new position on the screen 
(remember to keep the entire window visible when editing). 

-Scroil Bar 

The vertical bar on the right hand side of the window is the scroll bar. 
It allows you to scroll up and down within the current program file, 
selecting different blocks for editing. 

- Up Arrow 

Selects the previous block (numbered one less than the current 
block) as the block to edit. Stops on the first block in the file. 

- Down Arrow 

Selects the next block (numbered one more than the current block) 
as the block to edit. Stops on the last block in the file. 

- Scroll Box 

Drag the scroll box to select another block to edit. Move it up to 
edit lower numbered blocks and down to edit higher numbered ones. 

- Shaded Area 

Click inside the shaded area above or below the scroll box to move 
3 blocks at a time in either direction (up or down). 
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Now try a few of these features. First, click inside the close box. The editor 
window disappears and the MacFORTH window becomes the active window. To 
mal<e the editor window reappear, re-enter the editor by executing (from the 
MacFORTH window): 
5 EDIT 

With the edit window now the active window, here's how to move up in the 
file to block 4 click the up arrow in the scroll bar on the right side of the 
window. Click it once and it will move you up one block in the file ("up in the 
file" meaning to a lower numbered block). You'll see the title of the window 
change to 

Blk*4 of 23; File= FORTH Blocks 

indicating that you are now displaying block number 4 Return to block 5 for 
editing by clicking the down arrow in the scroll bar once. You can see that 
you have returned to block 5 by the title of the editor window; 
Blk*5 of 23; File= FORTH Blocks 

You can also move 3 blocks at a time in either direction in the file by clicking 
within the shaded area above or below the scroll box. Click in the shaded area 
below the scroll box once. You are now editing block 8 (you were previously 
on block 5). 

Each time you edit a new block, the scroll box is moved up or down. Its 
position tells you what block you are editing relative to the start and end of 
the file. 

By dragging the scroll box up or down within the shaded area, you can position 
the editor to edit any block in the file. Try dragging the scroll box to several 
different positions now. Simply drag it to a new location and release the 
mouse button to display the block being edited. 

Moving the scroll box to the top position in the shaded area will position you 
to edit block of the file. The bottom position in the shaded area positions 
you to edit the last block in the file. You can locate a particular block by 
positioning the scroll box in the approximate location from the beginning or 
end of the file. For example; since there are 23 blocks in the "FORTH Blocks" 
file, if you wanted to edit block 12 you would position the scroll box 
approximately half way between the top and bottom of the scroll bar. Try to 
find block 12 now using the above technique. 



Program Editing Page3-7 June 3, 1984 



Edit MeoM 

The Edit menu provides you with the following options while editing. Each 
item in the menu provides a powerful function at your fingertips (don't try 
these features just yet; simply read through the list to familiarize yourself 
with them): 

Undo (command Z) 

Undoes the previous cut, copy, or paste operation (Including any 
changes since the last operation). It actually restores the contents 
of the block to the version since the last cut, copy or paste operation. 

Cut (command X) 

Cuts the current selection range (discussed later in this chapter) 
from the text and places it on the clipboard. (Cut, copy and paste use 
the clipboard for consistency with the Macintosh environment). 

Copy (command C) 

Copies the current selection range (discussed later in this chapter) to 
the clipboard. 

Paste (command V) 

Inserts the contents of the clipboard to the block at the current 
cursor position and/or replaces the current selection range. 

Stamp (command S) 

Stamps the current block with the current date, as read from the 
internal clock, and initials stored in the user variable INITIALS. Use 
the word ©INIT to change the value in INITIALS. DATE displays the 
current initials and date stamp. If the first three characters in 
INITIALS are non-printable ASCII characters or blanks, the stamp 
function is disabled. 

Clean 

Blank fills the contents of the block currently being edited. Use this 
command with caution as you cannot undo it. 

Revert 

Resets the contents of the current block back to the version saved on 
the disc. Use this command with caution as you cannot undo it. 

Enter/Exit Editor (command E) 

Allows you to enter or exit the editor. 
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Insertion Point 

If you look in the editor window, you will see a flashing vertical bar. This is 
called the insertion point Try typing the phrase (type it in only, do not 
press Return): 

This is the insertion point. 

and you'll see it inserted at the insertion point. You can also see that 
everything to the right of the insertion point was shifted over each time a 
character was typed. Characters in the last position on the right were pushed 
right out of the window. Now delete what you just inserted by pressing the 
Backspace key once for each character you just entered (the key will repeat 
automatically if you hold it down). 

You can change the insertion point by pointing with the mouse to the position 
you want to insert text and clicking once. In the edit window, the cursor 
becomes an "I-beam" instead of an arrow to make it easier to select an 
insertion point between characters. Try moving the insertion point to several 
different places in the window now. Remember, position the i-beam cursor 
and click once. Each time you reposition it, the insertion point will be 
marked by the flashing vertical bar. 

Try repositioning the insertion point to several places again, but this time, 
each time you position the cursor, type the phrase "abc" and backspace it 
away to get a feel for inserting and deleting text. 

You can also insert a line at any point by positioning the insertion point and 
pressing the Return key. For example, position the insertion point between 
the words "Sample" and "Editing" in the first line and press Return. 
Everything on the line to the right of the insertion point is shifted down to 
the beginning of the next line, all lines below it are shifted down one line. 
Press the Backspace key once to "glue" the lines back together. When you 
pressed the Return key, you inserted a carriage return. Pressing Backspace 
deleted it. 

When you insert text in a line, all text to the right of it is shifted to the 
right. If you insert a Return, the text after the insertion point and all lines 
below are shifted down one line. You can recover the text that was pushed off 
the end of a line or the bottom of the screen by deleting some text (if off to 
the right) or deleting some lines (if off the bottom). To delete a blank line, 
just position the cursor against the left edge of the editor window and press 
Backspace. 

While you ean recover the text that has been pushed out of the window while 
you are editing, only the visible text is saved on the disc when you exit 
the editor. After any operation that saves the data in the disk buffers (stamp. 
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clean, undo, etc. — explained next) you cannot recover any text that you can't 
see. 

The MacFORTH editor uses a simple, yet powerful "cut and paste" style of 
editing (similar to MacWrite). By now, you can see how to insert and delete 
text at the insertion points by typing in new text or backspacing it away. 

Selection Rang e 

If you are familiar with MacWrite this description will be a review. Cut, Copy 
and Paste operate on a range of selected Information (le: a text string). To 
select Items for edit the I-beam cursor should be placed at the beginning of 
the desired text and dragged to the end of the "selection range". 

For example, try entering the following line in the block (put It anywhere you 
like): 

Uelcone to the vortd of riacFORTH editing!!! 

Now remove the word "MacFORTH" by selecting It and "cut"tlng It out: click at 
the beginning of "MacFORTH", drag to the end of the word (It is now displayed 
in inverse characters) and release the mouse button when the entire word is 
selected (entirely in inverse characters). Select the "Cut" Item from the 
"Edit" menu; the selection range is now deleted and saved on the clipboard. 
Bring It back by selecting "Paste" from the "Edit" menu. 

You can now reposition the Insertion point and paste the word "MacFORTH" 
anywhere In the current block. You can even move to a different block and 
paste It in that block! This should give you an Idea of the power of the editor. 
You can cut or copy a selection from any block and paste it Into any other 
block. 

Cleaning a Block 

The "Clean" Item In the "Edit" menu allows you to completely erase the 
current block being edited (filling the block buffer with blanks). THIS 
COMMAND CANNOT BE UNDONE, so use it with caution. You can only 
revert to the version of the block saved on disk. 



Reverting to the Last Version 

The "Revert" item in the "Edit" menu allows you to revert back to the old 
version of the block (from disc). All changes made to the block since it was 
last read In from disc will be lost. THIS COMMAND CANNOT BE UNDONE, 
so use it with caution. 
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The Editor stamp 

The MacFORTH stamp allows you to mark a block with your initials and the 
current date. Using this method informs you and others who last changed the 
block and what day the change was made. You should "stamp" the screen (by 
selecting the "Stamp" item from the EDIT menu each time you modify a block 
with the editor. 



Loading Blocks 

To load a block from disc, execute the LOAD command in the following form: 
<block«> LOAD 

For example, to load the block you were editing, execute 
5 LOAD 

When a block is loaded, the source code on the screen is interpreted Just as if 
you had typed it in from the keyboard. This enables you to mix definitions 
and commands to be executed immediately. 



Error Detection While Loading a Blocic 

If MacFORTH encounters an error while loading a block (an undefined word, a 
typo, missing delimiter, etc.), it will abort immediately and issue an error 
message. To find where the error occurred, simply enter the editor. The 
insertion point (flashing vertical bar) will be located just after the error. 

For example, if you have the sequence 
OUERTV 

in a block (and it was not a defined word) when you loaded the block, the 
insertion point would be one space after the "Y". This feature is invaluable 
for locating the cause of an error during loading because it shows you where 
MacFORTH encountered the error. 
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Listing Programs 

The following words are provided to enable you to list your programs to the 
display and/or printer. If you have an Apple Imagewriter connected to your 
Mac, select the "Printer" item from the "Options" menu to turn it on. All 
output to the screen will be sent to the printer as well. 

LIST 

Displays the specified block. The data, screen numbers, and lines of the 
block ( numbered 0-15) are displayed. For example; 

10 LIST 
would list the contents of block 10. 

INDEX 

Displays the first line of a range of blocks. If you follow the convention 
of using the first line of each block as a comment describing the 
contents of the block, INDEX will allow you to see quickly what a 
range of blocks contains. For example: 

5 15 INDEX 
would display the first line of blocks 5-15, with the block numbers 
displayed on the left. 

TRIAD 

Displays three sequential blocks on one page, starting with a block that 
is evenly divisible by three. You specify the number of any block in the 
"triad" that you want to display. For example: 

10 TRIAD 
displays blocks 9, 10 and 1 1. This enables you to update your program 
listings with only the screens that have changed. The icon used for 
MacFORTH blocks (program) files contain three rectangles to designate 
triad listings. 

SHOW 

Displays a range of blocks (as a series of triads). Given the starting 
and ending blocks to display, SHOW generates a listing of triads. For 
example: 

10 20 SHOU 
would generate a listing of three blocks per page containing the 
specified range of blocks (it would actually list blocks 9-20). 
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Copying Blocks 

The following routines allow you to copy the contents of one block (or blocks) 
to another (or others). 



Single Block Copying 

When copying limited numbers of blocks, use the COPY command in the 

following format; 

< source block«> <destlnation block«> COPV 

For example, to copy the contents of block 6 to block 5, you would execute: 
6 5 COPV 



Multiple Block Copying 

If more than a couple of blocks need to be copied, a copying utility program is 
available. Load these routines by loading block 10 of the "FORTH Blocks" file. 
To copy a series of blocks from one location on the disc to another, use the 
COPY.BLOCKS in the following format: 

<flr8t> <la8t> <larget> COPV. BLOCKS 

For example, to copy blocks 3 thru 7 to screens 12 thru 16, execute: 

3 7 12 COPV. BLOCKS (just an exanple; do not try this now!) 

During the copying procedure, you are shown which screens are being accessed 
with the following message: 

sss -> ddd 
where sss is the source block number and ddd is the destination block being 
copied. 



Copying Blocks from One File to Another 

Load the block transfer routines by loading block 12 of the "FORTH Blocks" 
file. The word XFER.BLOCKS will allow you to copy blocks between files, 
promting you to enter the required information. You will be asked for the file 
numbers of both files as well as the range of blocks to be transferred. 
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Blank-Filling Blocks 

To blank-fill a single block, select the "Clean" item from the "Edit" menu 

while editing the block. If you want to blank-fill a series of blocks, load the 

block copy routines (if you have already loaded them, you don't need to re-load 

them). You now have the word CLEAR.BLOCKS. It is used in the following 

format: 

<fir3t> <la8t> CLEAR. BLOCKS 

For example, to blank-fill blocks 20 thru 25 in the current blocks file, you 
would execute ( don't try this example): 
20 25 CLERR. BLOCKS 

Each time a block is cleared, the message 

ccc Cleared 
is displayed, where ccc is the number of the block being cleared. 



Cutting and Pasting to the Notepad 

You can cut, copy and paste selected text to/from the Notepad. This allows 
you to share ASCII data between MacFORTH and any other Macintosh system 
that lets you move data to the notepad. 

To move ASCII data from MacFORTH to the Notepad, enter the editor and cut 
(or copy) the desired text. Select the Notepad item from the apple menu and 
paste the selected text into the Notepad. 

To move ASCII data from the Notepad to MacFORTH, select the Notepad item 
from the apple menu and cut (or copy) the desired text. Enter the editor in 
MacFORTH and paste the selected text into a block. 
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Overview 

This chapter will give you first-hand experience in programming the 
Macintosh. You will enter a sample program, try it out, mal<e some changes, 
and try it again to see the differences. Don't try to understand each command 
now. The intent of this chapter is to give you a feel for programming the 
Macintosh, not to give a comprehensive description of each command. Later 
chapters will fill in the missing information. For now, just enter the example 
program and enjoy. 

By the time you finish this chapter, you will have created a new menu, defined 
a program to be executed for the window, tracked the mouse, created some 
graphics pictures (and printed them if you have an Apple Imagewriter 
printer), and defined a menu. 



Preparations 

By now you should have completed the Going FORTH tutorial, if you haven't, do 
so now before you continue. You will be instructed to edit some source code 
into the "FORTH Blocks" file. If you skipped the Program Editing chapter, read 
it now before you continue. 

It is important that you complete this chapter in one sitting. 

The only thing you'll need is about 20 minutes of time, your Mac, MacFORTH, 
and you. 

Restart your computer (by turning the power off then on) and load MacFORTH 
by opening the "FORTH Blocks" document from the Finder (by double clicking 
it). When MacFORTH loads, enter your initials when asked and you'll get "ok". 
You are now ready to start. 
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Finger Paint Example Program 

The example program you will be entering will allow you to create pictures in 
a new window using the mouse. Press the Return key a few times to see 
where your cursor is (some more "ok"s will appear). 

Prior to typing in the following example, resize the MacFORTH window and 
drag it down to the lower two-thirds of your screen (your screen should be 
similar to figure 4.2, except the Finger Paint window won't be present yet). 
This will expose the editor window. During the course of the following 
example another window will be defined and will appear in the upper left 
corner of the screen. 

One other reminder before you start typing; spaces separate words in FORTH, 
so pay careful attention to spacing in this example. 

You will use blocks 2 thru 4 of the "FORTH Blocks" file to enter the source 
code for this example, if there is already source code in any of the blocks, 
clean the block by selecting the "Clean" item from the "Edit" menu (be sure 
that you are editing the correct block before you clean it). 

Finally, remember to put the comment (in parentheses) in the topmost line of 
the block. 

Create a Window 

Edit the following source code into block 2: 

( Finger Painting Uindow Definition ) 

NEU.UIHDOU SHEET 

" Finger Paint Uindow" SHEET U. TITLE 

60 5 200 300 SHEET U. BOUNDS 

SIZE. BOX CLOSE. BOX + SHEET 14. ATTRIBUTES 

SVS.UIHDOU SHEET U.BEHIHD 

SHEET flDD.UIHDOU 
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Your block should now look like the block in figure 4.1. if there are 
differences go back into the editor now and correct them before you continue; 



^1 1 Hiir^ } nf M ; M»P=tnrth HInrlfS ============ 


( Finger Painting Uindouu Definition ) 


fe 


HEU.UifiDOW SHEET 


^ 


" Finger Paint Uindoui" SHEET U. TITLE 




60 5 200 300 SHEET U. BOUNDS 




SIZE. BOX CLOSE. BOK + SHEET U.fiTTRI ELITES 




SVS.UINDOU SHEET li. BEHIND 




SHEET flOD.UIHDOU 






S 



Figure 4.1 



Now load the block by executing: 
2 LORD 



At this point a new window will appear in the upper left corner of the screen. 

Resize your MacFORTH window and drag it towards the lower right corner of 
your screen so that both windows are visible (you can also see the editor 
window). Your screen should be similar to figure 4.2. 
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^ Options Edit 




Figure 4.2 



If you click in the new window the system will just beep at you. Click back 
inside the MacFORTH window and continue. 



Track the Mouse 

Edit the following source code into the top of block 3: 

( Finger Painting Source Code ) 

: TRACE. FINGER ( — I »ord to follow the mouse when down ) 

HIDE. CURSOR 
BEGIN STILL.DOUN UHILE ehOUSEHV DOT REPEAT 

SHOU. CURSOR : 
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Define the Window Program 

Edit the following source code into the bottom of block 3 (under the source 

code for TRACE.FINGER); 

! FINGER. PRINT ( actiyate flag ~ I progroB for SHEET ) 
IF BEGIN OO.EUENTS 

CRSE HOUSE. DOUN OF TRRCE. FINGER ENDOF 
IN. SIZE. BOH OF PRGE ENDOF 
ENDORSE 
RGRIN 
ELSE 7 SVSBEEP ( beep on deactivation ) 
THEN J 

SHEET ON.flCTIURTE FINGER. PR I NT 

Your block should now look like the block In figure 4.3, If there are 
differences, go back into the editor now and correct them before you continue. 



Figure 43 



Load the block by executing: 
3 LORD 
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=n Pil'# ^ nf ?T • Filr-Fnrth Rlnrt-c ""■.'.""'•''• j 


=( |.;,i ; 5 DiR."^ J ui £.-j , r iic~r til III DIUI.K9 ,.„i, ..,i ' ' 1 


( F i nger Pa i nt 1 ng Source Code ) 


S 


; TRACE. FINGER ( — 1 word to follow the mouse uihen down ) 


iijiii 


HIDE. CURSOR 


1 


BEGIN ST ILL. DOWN WHILE §nOUSEKV DOT REPEAT 


^ 


SHOU. CURSOR .; 




; FINGER, PRINT ( actiuate flag — 1 pr-ognam for SHEET ) 




IF BEGIN DO.EUENTS 




CASE nOUSE.DOUN OF TRRCE. FINGER ENDOF 


III 


IN.SIZE.BOK OF PRGE ENDOF 




ENDORSE 




RGRIN 




ELSE 7 SVSBEEP ( beep on deactiuation ) 




THEN ; 




SHEET ON.flCTIURTE FINGER, PR INT 


s 



Activate the finger paint window by pointing to it with the mouse and 
clicking down inside it. When you drag the mouse around in that window, the 
cursor disappears and a line follows where you move the mouse. You can even 
drag outside the window and come back in. When you release the mouse 
button (ie. stop dragging), the cursor re-appears and you don't get a line 
following you anymore. 

Try moving the cursor and clicking in the MacFORTH window now. The Mac 
beeps at you when you de-activate the SHEET window (its title is "Finger 
Paint Window) as you told it to do in FINGER.PAINT, Now resize the SHEET 
window so your drawing space is larger (but leave both windows visible). 

When you resize the SHEET window, the picture you drew is erased and you 
are given a clear space to work in. 

Close the sheet window (by clicking in its close box at the top left corner). 
To make it re-appear, execute (from the MacFORTH window): 
SHEET SHOU.UINDOU 

You can now activate the SHEET window and do some more drawing. 



Re-Title the Window 

Go back to the MacFORTH window (by clicking in it). Now change the title of 

the new window to your name. For example, if your name is Marge, execute; 

" narge'8 flrt»ork" SHEET SET.UTITLE 
or Harry: 

" Harry '8 lipreaaiona" SHEET SET.UTITLE 
or, if you prefer: 

" ny Uery Own Easel" SHEET SET.UTITLE 



Printing the Picture 

You can even print your work of art if you have an Apple Imagewriter printer. 
If you have one connected to your Mac, hold down the command key 
(immediately to the right of the Option Key) and the $ (shift 4) key 
simultaneously. If the Caps Lock key is up, only your sheet is printed, if the 
Caps Lock key is down, the entire screen is printed. 
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Define th$ Pen $lze Menu 

As the final addition to the program, create a menu to change the size of the 

pen you are drawing with. Edit the following code into block 4: 

( Pen Size flenu ) 

7 CONSTANT FINGER. SIZE. MENU 



! FINGER. riENU ( - 


-- ) 


FINGER. SIZE. tIENU 


DELETE. MENU 


" Finger Size " 


FINGER. SIZE. tIENU 


NEU.NENU 


" Snail jtlediui 


;Large" FINGER. SIZE. flENU 


APPEND. ITEHS 


DRRU.riENU.BRR 










FINGER.SIZE.NENU NENU. SELECT ION: 


HILITE.MENU 


GET.UINOOU 


>R 


SHEET UINDOU 






CRSE 1 


OF 


1 1 PENSIZE 


ENDOF 




2 


OF 


3 3 PENSIZE 


ENDOF 




3 


OF 


5 5 PENSIZE 


ENDOF 




ENDORSE 


R> 


UINOOU 






FINGER. MENU 











Your block should now look like the block in figure 4.4. If there are any 
differences, go back into the editor now and correct them before you continue. 



=1 1 ■ _ R||f# 4 nf ?^ ; FilP=Fnrth RlnrJr^ = 


( Pen Size Henu ) 


S 


7 CONSTflHT FINGER.SIZE.nENU 


III 


: FiNGER.ilENU ( — ) FIN6ER.SlZE.nEMU DELETE. HENU 


11 


" Finger Size " FINGER.SiZE.riENU NEU.HENU 


T^ 


" Sma ! 1 .! ned i um; Large" F 1 NGER . S 1 ZE . I1ENU APPEND . 1 TENS 
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Now load the block by executing: 

4 LOAD 
Now you will see the "Finger Size" menu on your menu bar line. Pull it down 
and select a new finger size. Activate the SHEET window and draw a few 
lines. Return to the "Finger Size" menu and select a new finger size. Draw a 
few more lines and re-select a new finger size. 

When you get tired of the current pattern, re-size the window and start all 
over if you like. 



Summary 

That's it! As we said at the beginning, our intent in this chapter was simply 
to introduce you to some of the features of the Macintosh, not to give a 
detailed description of each function. 

You've seen how simple it is to create a new window, assign a program to the 
window, track the mouse, create graphics pictures (and possibly print the 
result), and create a new menu. 
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Overview 

There are some basic features to the Macintosh you need to understand before 
you can use it effectively. To illustrate these features, we will present a 
series of examples, similar to the method used in Getting Started, but giving 
a more detailed explanation of the commands as they are presented. 

Many of the commands you will use in this chapter will be easy to understand 
at first glance. The example in which the command was introduced should 
make its usage clear. Others will require more explanation. We will explain 
the topic being presented and give any additional information you need to 
know to understand the example. If you want to know more about a particular 
command, refer to either the appropriate reference chapter of this manual or 
the glossary. 

As you go through this chapter, be sure that you try each example before you 
go on to the next, as we will use each step to build the next (very much like a 
FORTH program). 

Some of the examples are short enough that you can execute them directly 
from the keyboard without saving them (you will be instructed to "execute" 
the example). Others are longer and you may be asked to modify them later. 
To avoid re-typing the entire example, you will be instructed to save the 
example in a block on disc (using the editor ~ you will be instructed to "edit" 
the example, then "load" it). If you skipped over the Editor chapter, stop now 
and read it. We will assume that you know how to use the editor to complete 
this chapter. 

When MacFORTH words are included within text, they are printed in bold face 
capital letters to differentiate them from the rest of the text. We use the 
convention of capitalizing all MacFORTH words. This is by no means 
mandatory, as MacFORTH does not discriminate between upper and lower case 
(ie. WORDS is equivalent to words or Words, or even WoRdS) when 
executing the name of a definition. (If this is important to you, refer to the 
Advanced Topics chapter discussion of the LOWER.CASE option.) 
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Set Up a Work File 

We begin this section by creating a blocks file for you to use. If someone else 
has already gone through this chapter, the file may already exist. 



Displaying the Disk Directory 
Look at the contents of the disc by executing 
INTERNflL DIR 

This will display the contents of the disc directory. 



If the File Exists 

If the file "Work File Blocks" already exists (it is in the directory listing), 
someone else has created it. You only need to assign, open and select it. 
Execute the following (don't forget a space after the quotation marks): 

3 COHSTflHT WORK. FILE 

" Uork File Blocks" UORK.FILE RS5IGN 

WORK. FILE OPEN 7FILE.ERR0R 

UORK. FILE SELECT 



If the File Doesn't Exist 

If the file "Work File Blocks" doesn't exist (it doesn't appear in the directory 
listing), you need to create it. Execute the following (don't forget a space 
after the quotation marks): 

3 CONSTRHT UORK. FILE 

" Uork File Blocks" UORK. FILE RSSIGH 

UORK. FILE CREATE. BLOCKS. FILE ?FILE.ERROR 

UORK. FILE OPEN 7FILE.ERR0R 

12 UORK. FILE flPPEHD. BLOCKS 

UORK. FILE SELECT 

This will give you a working file named "WORK FILE BLOCKS" with 12 blank 
blocks to use as you complete this chapter. (You may want to keep it around 
as you go through the manual in order to keep any examples you might want to 
reload.) 
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File Commands 

The constant WORK.FILE is used as a convenient reference to the newly 
created file. You sliould use a constant when referring to a file for the sake 
of readability (it also mal<es it easier if you want to change its number at a 
later date). 

ASSIGN equates a file name with a file number. Future references to file 
number 3 (using the constant WORK.FILE) will access the file named "Work 
File Blocks". 

7FILE.ERR0R verifies the previous file operation and displays an error 
message if an error has occurred, 

CREATE.BLOCKS.FILE creates the blocks file on disc, making it a bootable 
file. Once a file has been created on the disc, there is no need to re-create it, 

OPEN opens the file as a blocks file and APPEND.BLOCKS alloted 12 blocks 
to the file for use, 

SELECT made the file the current blocks file for editing. 



Getting Results Page 5-4 June 4, 1984 



windows 

One of the most Innovative features of the Mac is its ability to create and 
display windows. Each window can be used for a different purpose and can 
run its own program. Let's begin this example by resizing the MacFORTH 
window to about two Inches high at the bottom of the screen. 

Drag the size box upwards to shrink the window to about two inches high. 
Next drag the entire MacFORTH window down to the bottom of the screen. 
Your screen should now look like figure 5. 1 below. 



# Options Edit Finger Size 



Blk# 23 of 23 ; Filft^Forth Blacks 




MacFORTH^" 1.1 ©1984 CS I 



ok 



Figure 5.1 

Next create a new window named TEST.W1ND0W, add it to the display, and 
assign it a program to execute. Execute the following: 

HEU.UINDOU TEST.UIHOOU 

TEST.UiNOOU ROD.UINDOU 

At this point the new window will appear and become the active window. 
Click in the MacFORTH window and continue. 
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NEW.WINDOW created a window definition named TEST.WINDOW. Each 
window created in MacFORTH has an array associated with it which defines 
the window. Information about the size, starting location, program to 
execute, text font, size, mode and style, etc. that pertains to the window Is 
stored in this array. When you want to reference your new window, use the 
MacFORTH word TEST.WINDOW which you just created. TEST.WINDOW will 
place the "window pointer" (or "wptr" in stacl< notation) for this window on 
the stack. 

The MacFORTH routines which manipulate windows require the window 
pointer for the window to be on the stack. This allows the window 
manipulation routines to be used for any window. 

All windows that can be displayed are kept in a list of windows maintained by 
the Macintosh. ADD.WINDOW Inserts the window specified (by its window 
pointer) Into the Mac's list of windows, displays It, and makes it the active 
window (unless the W.BEHIND window attribute Is set). 

Only one window can be active at a time. All input/output Is by default sent 
to the active window, To activate a new window, simply click the mouse 
down In the window that you want to become active. Click down in the new 
window and then back In the MacFORTH window. 

The default action of any window when It Is activated is to beep for all user 
events (mouse down, keystrokes, etc.). The ON. ACT IV ATE command allows 
you to specify the program to execute when the window is activated. 
Execute; 

TEST.UIHDOU ON.flCTIURTE QUIT 

to specify the program QUIT to execute when TEST.WINDOW is activated. 
QUIT Is the program which runs MacFORTH Itself (It waits for input, executes 
it, and responds "ok"). Now try clicking In TEST.WINDOW and pressing 
Return. Go back to the MacFORTH window (by clicking In it) and continue. 

You can also activate another window by using the SELECT.WINDOW 
command. SELECT.WINDOW expects the window pointer of the window to be 
selected on the stack. For example, to activate the new window from the 
MacFORTH window, execute: 

TEST.UIHDOU SELECT. U I NDOU 

and go back to the MacFORTH window by clicking In It. 

You can see that the MacFORTH window has both a size box and a close box; 
the editor window has only a close box, and the new window has neither. 
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These are all attributes about a window that can be Includecl or left off, 
depending on what you want the window to do. 

Try dragging each window around on the screen (If you don't know how to do 
this, run the Guided Tour provided with your Macintosh). Place them In any 
position you like, but be sure each window Is visible when you are done. 



Error Handling 

When an error occurs In a window other than the liacFORTH window, the 
MacFORTH window Is activated. The error message (If any) Is displayed In the 
MacFORTH window, not the window the error occurred In. 

This enables you to do any debugging from the MacFORTH window, allowing 
you to see when and how the error occurred. For example, activate 
TEST. Wl NDOW and execute; 
QUERTV 

and you win see the error message 
QUERTV ? 

appear In the MacFORTH window because MacFORTH doesn't understand the 
word QWERTY. 



Forgetting a Window 

When you forget a window, It Is removed from the Macintosh window list and 
taken off of the display (If visible). Forget your new window now by 
executing: 

FORGET TEST.UINDOU 

Any references to TEST. WINDOW, as with any other forgotten FORTH word 
will not be understood by MacFORTH as it has been removed from the 
dictionary. 
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Window Attributes 

Let's continue by creating a new window to worl< with. Edit the following 
example into block 2 of your "Worl< File Blocks" file: 
( New Uindow Exanple ) 
NEU.UIHDOU EH.UINDOU 

" Exanple Uindov" EX.UINDOU U. TITLE 
CLOSE . BOX S 1 2E . BOX + EX . U I HDOU U . RTTR I BOTES 

EX.UINDOU RDD.UINDOU 

Now load it by executing 
2 LORD 

You should now see a new window titled "Example Window" with a close box 
and size box. 

The default title for a window is "Untitled" (as you saw in the first window 
you created). W.TITLE allows you to assign your own title to a window. 
W.TITLE expects a string address on the stack (the string address was left 
on the stack by the word " ) under the window pointer. By executing 
" Example Uindow" EX.UINDOU U. TITLE 

in the above example, you assigned the title "Example Window" to the window 
EX.WINDOW (we refer to windows by their FORTH name for clarity.) 



Changing the Window Title 

You can also change the window title after it has been displayed using the 
word SET.WTITLE. For example, execute the following to change the name 
of the new window to "Example Workspace"; 

" Exanple Uorkepace" EX.UINDOU SET.UTITLE 

Activate the editor window now (by either clicking in it or choosing the 
"Enter Edit" item from the "Edit" menu). Its title is: 
Bik« 2 of 12; File » WORK FILE BLOCKS 

Now edit block 1 by clicking the up arrow of the editor control bar. The title 
of the menu changes to: 

Blk« 1 of 12; File - UIORK FILE BLOCKS 

The MacFORTH editor uses the SET.WTITLE command to change the title of 

the editor window each time a different block is displayed. 

EX.WINDOW also has two new features that the previous window you created 
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didn't have: a close box and a size box. The word W.ATTRIBUTES allows you 
to define the features of a window when it is created. These features were 
given to the window when you executed: 

CLOSE. 60}< SIZE.BOX + EX.UiHDOU U.RTTRI6UTES 



Closing a Window 

When you close a window, it is hidden from view, and the window closest to 
the "front" of the display is activated. Try closing EX.WINDOW now by 
selecting it with the SELECT.WINDOW command and then clicking its close 
box. Execute: 

EX.UINDOU SELECT. U I NDOU 

Then click in its close box. When EX.WINDOW disappeared, one of the other 
windows became active. Be sure the MacFORTH window is active by clicking 
in it. 



Hiding and Showing a Window 

From the above example, you saw how you can hide a window by clicking in its 
close box. To make a window re-appear, use the SHOW. WINDOW command. 
SHOW.WINDOW re-displays the window specified by the window pointer 
given. Execute the following to make EX.WINDOW re-appear: 
EX.UINDOU SHOU.UINOOU 

EX.WINDOW is now there, but it is behind the active window, in this case, the 
MacFORTH window. To see EX.WINDOW, close the editor window (enter the 
editor and click in its close box), then close the MacFORTH window by clicking 
in its close box. There it is!! Remember, SHOW.WINDOW makes the specified 
window visible, but not active. A "visible" window is on the desktop, but may 
be currently under another window. 

You can also hide a window with the HIDE.WINDOW command. Like 
SHOW.WINDOW, HIDE.WINDOW expects a window pointer on the stack. 
Return to the MacFORTH window by selecting the "MacFORTH Window" item 
from the "Options" menu. Execute the following to make EX. WINDOW 
disappear: 

EX.UINDOU HIDE.UINDOU 
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Window Bounds 

You can also determine the initial position and size of a window using the 
W.BOUNOS command. Edit the following example into block 3: 
( Ne« UindoH* TEST.UIND0U2 Exanple ) 

NEU.UINDOU TEST.UIN00U2 
" Test Uindo© 2" TEST.UIHD0U2 U. TITLE 
100 150 300 400 TEST.UIND0U2 U. BOUNDS 

TEST.UiN00U2 flDD.UINDOU 

Now load it by executing 
3 LORD 

You created a new window named TEST.WIND0W2, gave it the title "Test 
Window 7\ set its starting position to 100,150 relative to the top left corner 
of the screen (which is at 0,0) and made it a window 200 dots by 250 dots 
(400-150=250). 

The values 100 150 300 400 defined the window size by giving its "tlbr" 
values (for top, left, bottom, right). This is easy to remember, because any 
rectangle has four sides: top, left, bottom, and right. So in the example, the 
top of the window is at 100 dots from the top of the screen, the left side of 
the window is at 150 dots from the left side of the screen, the bottom of the 
window is at 300 dots from the top of the screen, the right side of the 
window is at 400 dots from the left side of the screen. 

The default value assigned to a window as its bounds is 
100 100 200 300 U. BOUNDS 



Hiding the Cursor 

You can hide the cursor (make it invisible) by executing the HIDE.CURSOR 
command. To make it reappear, execute the SHOW.CURSOR command. These 
commands are useful when you don't want the cursor to interfere with the 
process being performed. We used them in the Getting Started chapter finger 
painting example. 

Use them with one important caution in mind, however. The user expects to 
see the cursor move when she or he moves the mouse. If the cursor is hidden, 
it will appear that the system is not responding. If you hide the cursor for a 
time, be sure to make it reappear when you are done. 
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Modifying the Cursor 

You can change the type of cursor (currently an arrow) using the SET.CURSOR 
command. For example, to change the cursor to the wristwatch cursor (the 
cursor displayed when the Mac wants you to wait), execute: 
URTCH SET.CURSOR 

Return to the arrow cursor by executing: 
IN IT. CURSOR 

The optional cursors you can select with SET.CURSOR are: 
I BEAM (the cursor used In the editor) 
WATCH (the wristwatch) 

You can also fetch the current cursor with 6ET.CURS0R. This is useful for 
the times you want to change the cursor during a specific operation and then 
restore It to its previous image. The following example changes the cursor to 
a wristwatch during a delay loop, then restores the cursor to its previous 
image (enter it into block * 4): 
! DELRV ( — ) 

GET. CURSOR ( save the current cursor on the 
stack ) 
URTCH SET.CURSOR 10000 

DO LOOP ( a delay loop that does nothing } 
SET.CURSOR ; ( restore the cursor ) 

Load it by executing 
4 LORD 

and try a few tests: 

I NIT. CURSOR DELRV 
IBERn SET.CURSOR DELRV 

Remember, if you try 

URTCH SET.CURSOR DELRV 

you won't know when the test is complete until you get "ok". 

Execute 

INIT.CURSOR 

to return the cursor to the arrow before you continue. 
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Directing Output to a Window 

There are times you want to get Information or change some characteristic of 
a window without activating it, The commands WINDOW and GET. WINDOW 
allow you to access the information about a window without activating the 
window. WINDOW selects the window for output from the window pointer 
given on the stack, 6ET. WINDOW returns the window pointer of the current 
window. 

For example, the window EX.WiNDOW was created with the default text font 
and mode (these characteristics are discussed In detail in the graphics 
section, but for now, take our word for it). The MacFORTH window uses text 
font 4, and text mode 2. To set the EX.WINDOW text font and text mode to be 
the same as the MacFORTH window, edit the following definition into block 
five; 

: CHANGE. TEST ( — ) 

GET.UINDOU ( save current wptr on the stack) 
EX.UINDGU UINDGU ( select EX.UINOOU ) 
CR ." Before..." 

4 TEKTFOHT ( select the text font ) 

2 TEXTnODE ( select the text node ) 

CR ." After" 
UINDGU j ( restore the window } 



Load it via 



CHANGE. TEST 



5 LORD 



and CHANGE.TEST is defined then executed. When WINDOW is executed, It 
makes the selected window the current window for output If you execute 
WINDOW outside of a definition (via the keyboard), be sure to re-select the 
window to the MacFORTH window when you are through (the name of the 
MacFORTH window is SYS.WINDOW). 

You can see that the word "Before" was displayed in the default Macintosh 
font. "After" was displayed in the MacFORTH default textfont. 
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The Mouse 

You can read the current position of the mouse at any time with the word 
#liOUSEXY. The x and y coordinates of the mouse are returned on the stack. 
Here's a word to follow the mouse and report its current position relative to 
the active window: 

: TRACK. nOUSE ( — ) 

BEGIN CR ." House fit: " sHOUSEXV SURP . . 
RGRIH ; 

TRACK. nOUSE 



This will send you into an infinite loop which prints the current position of 
the mouse. Try it out. Move the mouse all over the screen and you'll see the 
position change. 

To get out of this word (or to escape from any endless loop that displays 
output), select the "Abort" item from the "Options" menu. 



Text Output 

So far, we have used ." exclusively as the way to output character data. You 
can also type a string from memory or emit a single character. The word 
EMIT displays the ASCII character given on the stack (refer to the ASCII 
Chart Appendix for specific ASCII characters). For example, to output an 
asterisk, execute (in decimal); 
42 EfllT 

To type a string from memory, use the words COUNT and TYPE. MacFORTH 
strings contain the length of the string in the first character position, 
followed by the string itself, Given the address of a string, COUNT returns 
the address of the first character in the string under the length of the string 
(in bytes). TYPE displays memory (usually a string address converted by 
COUNT), given an address and length on the stack. 
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Creating a S tring 

There are many ways to create strings In MacFORTH. Here are the two most 

common methods: 

a.) The word " creates a string (delimited by ") and leaves its address on the 
stack. You have already used this technique when defining window and 
file names earlier in this chapter. The format for this method is: 
" <8trlng>" 

Remember, the leading quote is a MacFORTH word, it must have a space 
before and after it. The space after it is not included in the string, it 
separates the string from the forth word " . The delimiting quote does 
not need a space before it, but it does need a space after it. For example, 
to create and display a string containing the name of the first NASA 
Space Shuttle, you would execute: 
" Columbia" COUNT TVPE 

The disadvantage to this method is that the address of the string is only 
available immediately after the phrase is executed. Use this method 
when you only n eed the string once. 



b.) You can create a named string using CREATE and / in the following 
format: 

CREATE <8trlng naie> / <9trlng>" 

Like " , you must have a space immediately following ," . The advantage 
to this method is that you can refer to the string by name. For example, 
to create a string containing the name of the second NASA Space Shuttle, 
execute: 

CREATE SHUTTLE$ / Challenger" 

To display the name, execute: 
SHUTTLES COUNT TVPE 
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Keyboard Input 

MacFORTH allows you to control input from the keyboard from the level of a 
single keystroke at a time to input of numbers and strings. 

input of Keystrokes 

The word KEY traps ASCII keys from the keyboard (command keys are 

executed automatically) and returns the character value on the stack (refer to 

the ASCII chart appendix for the ASCII character values). For example, 

execute; 

KEV . 

and press the "*" key (shifted 8), and you'll see that the ASCII character value 
for asterisk is 42, When KEY executes, it does not display the keystroke (as 
you saw, the * was not displayed). If you want the keystroke displayed, 
duplicate the value (with DUP) and EMIT it. This word is handy for words 
like: 

: flNSUER.V/N ( -- flag I flag - -1 If V, If anything else ) 
." Answer Ves or No (V/N) ->" KEV DUP EniT 89 ( V ) - ; 

Now try executing ANSWER.Y/N and responding with uppercase Y or N. The flag 
returned on the stack is true if a capital Y was pressed. Now try it out. 
Execute 

fiHSUER.V/H . 

and press uppercase Y, Now try the same test, but this time press a different 
key. 

If you wanted to look for either an upper or lowercase Y, you could modify 
ANSWER.Y/N and replace the phrase 
89 ( V ) - 

with; 

DUP 89 ( V ) - SURP 121 ( y ) - OR 



Number input 

To input a number using MacFORTH, use INPUT.NUMBER. INPUT.NUMBER 
accepts a number of up to the width specified (in digits). After you press 
Return, the number is converted from a string to binary. If the string is a 
valid number, the number is returned on the stack under a true flag. If the 
string is not a valid number, only a false flag is returned. 
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Try: 

5 IHPUT.HUriBER CR . . 

After you press Return, MacFORTH will be waiting for input. Input the number 
123, then press Return. The numbers on the top of the stack are -1 and 123. 
This indicates a number was input, and the number is 123. Now try another 
example. Execute: 

5 INPUT.HUflBER CR . . 

Again, after you press Return, MacFORTH will be waiting for input. This time, 
input an invalid number. Input 
DUD 

Since "DUD" is not a valid number, a was returned on the stack under a -1, 
indicating a string had been input, but it was invalid. 

During conversion of the string to binary, if an invalid numeric character (not 
thru 9 or minus sign) is encountered, MacFORTH will stop converting the 
string to a number. The number converted up to that point will be returned on 
the stack under a true flag. If the first character is invalid, a zero is 
returned under a true flag. 

If nothing is input (the operator just presses Return), a zero flag is returned. 

If this seems like a lot of things to remember for just inputting a number, you 
could define a word like: 

: RSK.NUriBER ( ~ n ) 

BEGIN CR ." Input Nunber ->" 3 IHPUT.HUnBER UNTIL ; 

When ASK.NUMBER is executed, it will repeat the prompt "Input Number ->" 
until a number is entered, and leave the converted number on the stack. 



String Input 

The word INPUT.STRIN6 accepts a string of characters from the keyboard. It 
takes an address to store the string under maximum number of characters to 
input (up to 255). This way you can control how many characters can be input. 
When INPUT.STRING is executed, the system will stop what It is doing and 
wait for a string to be input. The following example will input a string of up 
to 12 characters to PAD (the MacFORTH scratchpad buffer), and then display 
it. Remember, once you execute INPUT.STRING (by entering the following 
phrase), the system will wait for a string to be input. Now try: 
PAD 12 INPUT.STRING 

After you press Return, MacFORTH will wait for you to input a string. Input 
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the string (up to 1 2 characters) and press Return. To see the string you input, 
execute: 

PAD COUNT TVPE 

You can also use INPUT.STRING to input into a string variable. The following 
example will create a string variable named NAMES and input a string into it: 

CREATE HflflES ," Bill Silth" 

NfltlES COUHT TVPE 

After you enter the next line, the system will wait for you to enter the name 
string, so input the name Joan Jones. 

HRtlES 10 INPUT.STRING 

NflttES COUNT TVPE 

Warning: If you try to enter a string longer than the original string into a 
string variable, you will overwrite part of the dictionary and may cause the 
system to crash. Be sure that the string variable you are using is long enough 
by counting the number of characters in it. An easy way to create a string 
variable of the proper length is to use numbers in the string. For example, to 
create a string variable 18 characters long, you could execute: 

CREATE nV$ / 123456789012345678" ( 18 char string ) 



Window Function 

The default program for a newly created window when it is activated is to 
just beep at all mouse clicks or keystrokes. You can assign a program to a 
window using the ON.ACTIVATE command. When the window is activated, 
the program assigned to it is executed. 

When a window is activated, its program is passed a flag telling whether it is 
being activated (a true flag) or deactivated (a false flag). The program then 
determines what to do and runs. 

When a window is deactivated (by activation of another window, or by closing 
the window), the program it is running is aborted immediately, and the 
activated window is given control to run its program. 

To illustrate this point, activate the MacFORTH window and execute the 
following: 

: TEST ( — ) 

100 DO I . LOOP CR ." Test Done" ; 

TEST 
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As you would expect, TEST displayed the numbers through 99, output a 
carriage return and displayed "Test Done". 

Execute TEST again, but this time, before it completes, activate EX.WINDOW 
(by clicking in it). As soon as you activated EX.WINDOW, did you see that 
TEST stopped executing and control was passed to EX.WINDOW? Re-activate 
the MacFORTH window and you'll get "ok", indicating TEST was aborted, and 
MacFORTH is waiting for your next request. 



Assigning a Program to a Window 

You assign a program to a window using the ON.ACTIVATE command. This 
program will replace the default program. Any program assigned to a window 
will be passed a flag when the window is activated telling it whether the 
window was activated (a true flag) or deactivated (a false flag). This allows 
you to do any initialization when the window is activated, and perform any 
clean up when the window is deactivated. Your program must be aware of this 
flag and handle any special cases for activation or deactivation. 

To illustrate this feature, assign a program to EX.WINDOW and watch it run. 
Edit the following example into block ^6 (and then load it): 

: TEST.flCTIUflTE ( flag -- I true if actiuate, othemiae 
false ) 
IF ." Window Rctivated!!" 3 SVSBEEP UORDS 
ELSE ." Window Dead iyatedl! " 3 SVSBEEP 
THEN ; 

EX.UINDOU ON.fiCTIUflTE TEST.flCTIUflTE 

ON.ACTIVATE assigned the program TEST.ACTIVATE to EX.WINDOW 

Activate EX.WINDOW by either clicking in it or using SELECT.WINDOW. 
When the window is activated, it will run the program TEST.ACTIVATE, 
which displays the message "Window Activated!!", and executes WORDS. When 
WORDS has completed, it will pass control back to the MacFORTH interpreter, 
which will display "ok". 

Now click down in another window. When the window is deactivated, 
TEST.ACTIVATE will be executed again, but this time a false flag is passed, 
indicating the window is being deactivated. The message "Window 
Deactivated!!" will be displayed, and control is passed to the newly selected 
window. 
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Window Function Template 

Each program assigned to a window should be similar to the following 
template: 

: U I HDOU. FUNCTION ( actiuate flag -- ) 

IF <actiuate code> 

ELSE < deactivate code> 

THEN J 

This is discussed in more detail in the Windows chapter. 



Multiple Windows 

The number of windows you can have and display at the same time is limited 
only by the amount of memory available. When a window is activated, its 
program will run until it completes or another window is activated. 



Menus 

Another important innovation of the Macintosh is the use of menus. Menus 
allow you to present a large number of options to the user while at the same 
time not requiring her or him to go through several layers of traditional 
menus or remembering a large number of commands. 

For a detailed discussion of menus, refer to the Menus chapter of this manual. 
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Sound Generation 

The Macintosh supports a wide range of sound capabilities. liacFORTH 
provides access to the ROM sound driver for complex sounds (free form and 4 
voice wave form) as well as versatile support for simple square wave tone 
generation. 

Simple Tone Generation 

In order to generate distinctive sounds to alert the operator or play simple 
melodies, MacFORTH provides the word TONE. TONE expects three things on 
the stack: 

durat i on\vol ume\f requency 

Duration is expressed in increments of 1/60 of a second "ticks" and is in the 
range through 256 (0-45 seconds). 

Volume Is expressed in a scale from 1 through 256, with 256 representing the 
loudest. 

Frequency Is expressed in hertz * 10. 

For example, 

60 128 1000 TONE 

will generate a tone of 100 Hz at half volume for 1 second. Here are a few 
others to try: 

60 128 100 TOHE 

60 128 10000 TONE 

120 64 30000 TONE 



Detecting Sound in Progress 

The word ?SOUND lets you check to see if a tone, or series of tones is 

currently being sounded. 



Aborting Sound in Progress 

The word HUSH allows you to abort any sounds currently being generated. 



Re s t Note s 

A frequency of waits the supplied duration with no sound output. 
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Note/Frequency Equivalence 

The following table provides frequency equivalents for notes in an 8 octave 

human tempered scale: 

Octave (frequency* 1 0) 



Note 





i 


2 


3 


4 


5 


6 


Z 


C 


164 


327 


654 


1308 


2616 


5233 


10466 


20930 


C* 


173 


348 


693 


1386 


2772 


5544 


11087 


22175 


D 


184 


367 


734 


1468 


2937 


5873 


11747 


23493 


D* 


194 


389 


778 


1556 


3111 


6223 


12445 


24890 


E 


206 


412 


824 


1648 


3296 


6593 


13185 


26390 


F 


218 


437 


873 


1746 


3486 


6985 


13969 


27938 


F* 


231 


462 


925 


1850 


3700 


7700 


14800 


29600 


G 


245 


490 


980 


1960 


3920 


7840 


15680 


31360 


G* 


260 


519 


1038 


2072 


4153 


8300 


16612 


33224 


A 


275 


550 


1100 


2200 


4400 


8800 


17600 


35200 


A* 


291 


583 


1165 


2331 


4662 


9323 


18647 


37293 


B 


309 


617 


1235 


2469 


4939 


9878 


19755 


39511 



Arrays 

Arrays are simple! An array is just an area of memory you set aside to store 
data in. You decide what is kept in the array and how the data is accessed. 
This can range from a very simple, one dimensional array storing single 
characters to a multi-dimensional array storing a complex data Item. 

Creating an Array 

To create an array, you simply assign a name to an area of memory and 
allocate the amount of space you need. Use CREATE to name the area and 
ALLOT to allocate the space. For example, to allocate space for an array 
which will hold the ages of 10 of your employees, you would execute: 
CREATE AGES 10 ALLOT 

You now have an area of memory allocated (10 bytes to be exact) to the array 
AGES. Since the values in this array will each fit Into 1 byte (0-255), only 
1 bytes are needed. 
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If you wanted to create another array which would keep track of their 
salaries (in the range $15,000-$75,000), each element in the array would 
require 4 bytes (a 32-bit integer). You could create an array named 
SALARIES for this information: 
CREATE SflLflRIES 10 4* fiLLOT 

Why did we specify 10 4* instead of 40? Which do you think describes ID 
elements, each 4 bytes long better?? 



Initializing the Array 

You can initialize an array in many ways. The MacFORTH words ERASE and 
BLANKS are convenient for zero and blank filling arrays. Try zero filling the 
AGES array now by executing: 
RGES 10 ERRSE 

(Refer to the MacFORTH Glossary entry for FILL for a general purpose word to 
fill memory with any character.) 



Accessing Data in an Array 

Given the base address of the array (given by its name), you can add the 
appropriate offset to calculate the address of any element in the array. For 
example, to get the first element in the AGES array (with subscript 0), you 
would execute: 
RGES Ce . 

and you'll see that the value is zero. To read the second element in the AGES 
array (with subscript 1 ), you would execute: 
RGES 1+ Ce . 

and so on. Remember, the subscript of an element is zero based, meaning that 
the first element is subscript 0, the second, subscript 1, the third, subscript 
2, and so on. This is logical if you think of the start of the array as the base 
of the array, and each element is just an offset from the base. The first 
element is located at the base, the second is located one up from the base, 
and so on... 

Storing data in the AGES array is just as easy. For example, to store 27 in 
the third element (subscript 2), you would execute: 
27 RGES 2+ C! 

Since each element in the AGES array is one byte long, calculating the 
address of any element is as easy as adding its subscript to AGES. In the 
SALARIES array, it is almost as easy. 
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Each element in SALARIES is 4 bytes, so you need to multiply the subscript 
by 4 (the length of each element) to get the address of any element in the 
array. For example, to get the first element (subscript 0), you would execute: 
SflLflRIES e . ( or ) SflLfiRIES 4*+ e . 

To get the third element (subscript 2), you would execute; 
SflLflRIES 2 4* + e . 

Why did we use 2 4* + instead of 8? The first expression tells you that you 
were getting the second 4-byte element, the second is ambiguous. Of course, 
the latter is more speed efficient. 

Here's a word to display each element in the AGES array: 
: SHOU.flGES ( — ) 

10 DO CR I . ." - " RGES 1+ Ce . LOOP j 

or, each element in the SALARIES array: 
: SHOU. SflLfiRIES ( — ) 

10 DO CR I . ." = " SflLflRIES I 4* + e . LOOP ; 

You've noticed by now that MacFORTH doesn't check to see if you are using a 
valid subscript when accessing an array. This saves the tremendous overhead 
of checking each and every subscript each and every time an element in the 
array is accessed. It is your responsibility to check the values when 
necessary. 

As we said, what you do with an array and the data you keep in it is 
completely up to you. Arrays in MacFORTH are free-form areas of memory. If 
you are new to FORTH programming, some interesting words to remember 
when using arrays (or any time you are manipulating memory) are: 

e I Ue Ul Ce C! CnOUE 

FILL 



Memory Allocation 

Memory in the Macintosh is allocated from a pool of available memory called 
the "heap." Although most memory allocation is handled automatically by 
MacFORTH, there are two areas which you must be aware of and explicitly 
control: the object and current vocabulary areas. We leave the allocation of 
memory up to you in order to give you more control of this resource. 
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When a new word is created in MacFORTH, the name is placed in the current 
vocabulary area (usually the FORTH vocabulary). The parameter field (which 
includes data and memory address or 68000 instructions used by the word) is 
placed in the object area. 

The current vocabulary and object space are initially allocated 20Kand iOK 
bytes respectively. If you need more room while compiling a program and you 
get one of the following error messages: 

VOCABULARY FULL! 
or 

OBJECT FULL! 
you will need to resize the appropriate space. 



Displaying the Amount of Memory Available 

You don't have to wait until you get one of these errors in order to resize the 
appropriate space. You can monitor both areas as you add definitions by 
executing the word ROOM See how much room you have allocated and 
available now by executing 
Roon 

and you will see the display: 

aaaa OF bbbb Object Bytes Available 
cccc OF dddd Current Vocabulary Bytes Available 
eeee Heap Bytes Available 

aaaa is the number of unused object bytes available and bbbb is the total 
number of object bytes allocated. Subtracting aaaa from bbbb will give you 
the number of object bytes used). 

cccc is the number of unused bytes in the current vocabulary and dddd is the 
total number of bytes allocated. Subtracting cccc from dddd will give you the 
number of current vocabulary bytes used). 

eeee is the amount of heap space available. This tells you how much memory 
is available for use. 



Resizing Memory 

You explicitly specify the amount of space to be used by either the object 
space or current vocabulary space. This way you can increase or decrease 
either as you needs require. 

To resize the object space, use the command RESIZE.OBJECT, specifying the 
amount of space to allocate to the area, For example, to allocate 10,500 
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bytes to the object area you would execute: 
10500 RESIZE. OBJECT 

To resize the current vocabulary space, use the command RESIZE.VOCAB, 
specifying the amount of space to allocate to the area. For example, to 
allocate 9500 bytes to the current vocabulary space you would execute: 
9500 RESIZE. OBJECT 

After resize either memory area, it is wise to verify the change by executing 
ROOM. You will notice the amount of heap bytes available change as well as 
the amount of space allocated to the area modified. 

If you try to allocate more space than is available, or to shrink either memory 
area smaller than Its current contents, MacFORTH will issue an error 
message. Refer to the Error Handling chapter for more information when one 
of these errors occurs. 
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Overview 

This chapter discusses how to produce graphics images on the Macintosh, it 
is intended to introduce you, through examples, to each of the features of the 
liacFORTH graphics package. We will use the analogy of drawing with a pen on 
a piece of paper for clarity. 



Preparations 

It's a good idea to complete this chapter in one sitting. If you have read 
straight through the preceding chapters you may want to take a break, then 
come back to this chapter. 

As you go through this chapter, let your imagination run free. Explore. Be 
creative! Our examples are intended to trigger your own examples. Of all the 
wonderful things that Macintosh graphics is, perhaps the most important 
feature is that it's fun to use! 



QuickDraw": A Solid Base 

QuickDraw is the underlying graphics package from which the Macintosh User 
Interface (ie; menus, windows, etc.) is constructed. Written by Bill Atkinson 
at Apple, QuickDraw represents many major innovations in graphics software 
technology. 

QuickDraw lives up to its name! It's very fast. You can do good quality 
animation, fast interactive graphics, and complex yet speedy text displays 
using the full features of QuickDraw. Using QuickDraw, you can divide the 
Macintosh screen Into a number of individual windows. Within each window 
you can draw: 

- Straight lines of any length and width. 

- Text characters in a number of proportional and fixed spaced fonts, 

with variations that include boldface, italics, underline, shadow, 
and outline. 

- A variety of shapes, either solid or hollow, including: rectangles with 

or without rounded corners, ovals, arcs, and wedges. 

- Any other arbitrary shape or collection of shapes, again either solid or 

hollow. 

- A picture consisting of any combination of the above items, with just 

a single operation. 
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In addition, QuickDraw has some other abilities that you won't find in many 
other graphics packages. These features take care of most of the 
"housekeeping" ~ the trivial but time-consuming and bothersome overhead 
that's necessary to keep things in order: 

- The ability to define many distinct windows on the screen, each with 
its own complete drawing environment — its own coordinate system, 
drawing location, character set, location on the screen, and so on. You 
can easily switch from one such window to another. 

- Full and complete "clipping" to arbitrary areas, so that drawing will 
occur only where you want. You don't have to worry about accidentally 
drawing over something else on the screen, or drawing off the screen 
and destroying memory. 



MacFORTH provides you with direct access to most of the features of 
QuickDraw. Upon this strong foundation we have built a two dimensional 
graphics package capable of translating pictures and images which are 
expressed in natural user coordinates (ie; feet, miles, furlongs, centimeters) 
into actual images on the screen. The images that you create may be offset, 
rotated and scaled with respect to the window in which you are drawing. 



Your Window, Your Canvas 

All drawing occurs within the content region of a window. The content region 
of a window is the area inside the window excluding the title bar and any 
control bars. Each window is a complete and separate drawing environment 
that defines how and where graphic operations will have their effect. Each 
window has it's own coordinate system, drawing pattern, background pattern, 
pen size and location, and character font size and style. You may instantly 
switch between windows for graphic output. 



The MacFORTH Window 

In the following examples, you will use the MacFORTH window for graphics 
output. Although both interactive transactions with MacFORTH and graphics 
output will occur on the same window, we will later discuss how to do each 
in separate windows. 

Now, resize the MacFORTH window to take up most of the available desktop 
space. (If you don't understand how to do this, run the Guided Tour to 
Macintosh and review the preceding chapters). 
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6INIT: Graphics Initialization 

Execute 

GIHIT 

This will restore the state of the graphics system to it's default state. If, 
during the remainder of this chapter, you become confused as to what is going 
on (e.g. drawing in white ink on a white background) use GINIT to restore the 
system to a known state - black ink on white background. You will notice that 
the cursor moves immediately to the upper left corner of the window. 



The Native QuickDraw Coordinate System 

GINIT also resets coordinate interpretation to QuickDraw native mode, and 
places the pen at 0,0. Let's move the origin to the center of the screen and 
display the X/Y axis. Execute 

CENTER XYAXIS 

QuicicDraw native coordinates are different from the normal 
cartesian coordinates that that you learned in school: 



Cartesian Coordinate Sytem 



Higher T 

/\ 



I (0,0) 
Lower 'X < > Higher 'X' 



\/ 
Lower 'Y' 

As you can see, in the Cartesian coordinate system, increasing Y values 
progress y£, increasing X values progress to the right. 
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Look carefully at the XY axis that we've put up on the screen. The *+" sign for 
the Y axis (up an down direction) is at the bottom, not the top (where it would 
be in Cartesian coordinates). 



QuickDraw Coordinate System 



Lower 'Y' 

/\ 



Lower 'X <- 



(0,0) 



-> Higher 'X' 



\/ 
Higher T 

Note that in native QuickDraw coordinates, increasingly higher Y values 
progress down, and lower Y values progress u£. X coordinates are the same in 
both Cartesian and QuickDraw coordinate systems. Now you can see why the 
cursor is moved to the upper left corner when 61 NIT is executed. It was 
initialized to 0,0. The diagram below shows how your window relates to the 
coordinate system: 



( top left corner of screen -- ) 

V 



-> higher 'x' 



0,0 

Mac 
Window 
or Page of 

Text 



\/ 
higher 'y' 

Although native QuickDraw coordinates are aligned with the way a page of 
English text is read, it's still different from the way you may have been 
taught in school to think about coordinate systems. 
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Execute the following example: 

10 10 nOUE.TO 50 50 DRRU.TO 

This will move the pen to 10, 10 and draw a line to 50, 50. Notice the line 
slopes downward. 

MOVE.TO expects two values on the stack (the x and y coordinate of a point), 
and moves the starting point for drawing to that position, if you think of 
drawing lines with a pen, MOVE.TO simulates lifting the pen off of the paper 
and moving it to the specified location. 

DRAW.TO expects two values on the stack (the x and y coordinate of a point), 
and draws a line from the current point to the specified point. The new 
location becomes the starting point for the next operation. If you think of 
drawing lines with a pen, DRAW.TO simulates keeping the pen down as you 
move it to the specified location. 



The Basis of QuickDraw 

Without discussing the mathematics behind QuickDraw's relationship to the 
physical layout of graphics memory systems, it may be a little difficult to 
understand why this coordinate system was chosen. 

Most major innovation is the result of relaxing traditionally accepted 
constraints and discovering whole new ways of looking at the problem. 
Consider "Reverse Polish Notation". By removing the constraint of jumbled 
operators and operands, far simpler and more elegant code may be produced by 
always having operators follow operands and keeping intermediate values on a 
stack. 

By relaxing the Cartesian Y coordinate constraint. Bill Atkinson was able to 
construct a mathematically pure model capable of expressing a two 
dimensional coordinate system on bit mapped graphics screens. Much of the 
startling performance of the QuickDraw package is the result of the far 
simpler arithmetic relationships between points in graphics memory and 
QuickDraw native coordinates rather than Cartesian coordinates. 

Don't panic. You don't have to learn a new method of drawing points if you 
don't want to. MacFORTH allows you to express points in the Cartesian 
coordinate system if you prefer. 
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Try the following example: 

CRRTESIRH ON ( specify the Cartesian systei ) 

PRGE ( clear the vindov ) 

CEHTER ( center the xy axis in the windov ) 

XVRXIS ( display the xy axis ) 

10 10 tlOUE.TO 50 50 DRRU.TO ( dran a line } 

The line that was drawn slopes upward, just as you would expect it to when 
drawn in a Cartesian coordinate system. To go back to the native QuickDraw 
coordinate system, execute: 
CRRTESIRH OFF 

That's how easy it is to change between the two coordinate systems! 



Range of Coordinates 

Coordinate values are between -32768 and +32767 for both X and Y. Based 
upon where you place the axis origin, points that are calculated to appear 
within the window will be displayed; all others are not. Execute: 

CRRTESIRH ON 

CEHTER ( discussed later ) 

10 10 nOUE.TO 1000 1000 DRRU.TO 



Notice that the line was drawn right off of the window. Now execute: 
20 10 nOUE.TO 100000 100000 DRRU.TO 

Numbers greater than 32767 "wrap around" to the negative end of the 
coordinate system. Although MacFORTH deals with numbers up to +/- 2 
billion, coordinate values greater or less than +/- 32767 can be best 
described as "undefined". Refer to the "Scaling to User Coordinates" section 
of this chapter for how to deal with larger numbers. 



A Handy Tool 

Enter the following definition to save yourself some typing: 

! CLERH ( — ) PAGE CENTER CRRTESIRH ON XVRXIS j 

When writing and testing MacFORTH programs, any repetitive sequence should 
be defined and given a name. From now on we'll just use CLEAN to clean up 
the display and redraw the xyaxis. Try it out now, execute: 
CLERH 
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Here's a quick summary of the commands we have presented so far: 
CARTESIAN OFF Sets mode to native QuickDraw coordinates 
CARTESIAN ON Sets mode to cartesian coordinates 
CENTER Positions the XY origin in the center of the window 



CLEAN 



DRAW.TO 



GINIT 

MOVE.TO 

PAGE 

XYAXIS 



Wipes the display and places the xyaxis in Cartesian 
coordinates on the screen 

(this word is only present If you enter the definition 
given on the previous page) 

Draws with the pen to the specified location from 
the current location 

(for now use MOVE.TO before every DRAW.TO on the 
same line) 

Reverts to Macintosh native coordinates and places 
the XY origin in the upper left corner of the window 

Moves the pen to the specified location 

Clears the screen 

Displays the XY axis 



Line Drawing 

As you have seen, lines are defined by two points: the current pen location 
and a destination location. When drawing a line, QuickDraw moves the pen 
(actually the top left corner of the pen) along the calculated line from the 
current location to the destination. 

If you draw a line to a location outside your window the pen location will 
move there, but only the portion of the line that is calculated to be inside the 
window will actually be drawn. This is true for all drawing procedures. 
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window Pen Characteristics 

The graphics "pen" associated with each window has the following unique 
characteristics: 

a location 

a size and shape 

a drawing pattern 

a drawing mode 

Pen Location 

The pen location is a point in the coordinate system of the window and is 

where QuickDraw will begin drawing the next line, shape, or character. 

Within the range of coordinates there are no restrictions on the location or 

placement of the pen. Remember, if you position the pen outside of the 

window, you won't see part of the next line or shape drawn (if you leave it 

there). 

As you have already seen, MOVE. TO positions the pen at the specified 
location, and DRAW.TO draws from the current location to the specified 
point. 

Notice the emphasis that DRAW.TO draws from the current location. To 
illustrate this point, execute the following example (on three separate lines): 

CLERN 

10 10 nOUE.TO 

100 100 DRRU.TO 

What happened?? Let's try it again, one step at a time. Execute: 
CLEAN 

You see that the window was cleared, the xy axis was displayed, and the "ok" 
was displayed in the upper left corner. Next, execute: 
10 10 nOUE.TO 

look at the xy axis, where the point (10,10) is. See the "ok"? This tells you 
where the pen location was moved to. After MacFORTH processed the 
command, it output the "ok" and then moved the pen to the start of the next 
line (at the current cursor position). Each time you enter a character, the pen 
location is moved to the right (at the position of the cursor). So, when you 
exuecte: 

100 100 DRRU.TO 

Where was the current location when the command was processed? At the 
cursor position, just to the right of the DRAW.TO command. 
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This is why you were given examples with MOVE.TO and DRAW.TO on the 
same line. Now try: 

CLEAN 

10 10 nOUE.TO 100 100 DRRU.TO 

and you'll see the line you expected. Remember, the current pen location is 
changed when MacFORTH finishes what you just asked in interactive (or 
interpretive) mode. While running a program, your pen will move only to 
where you specify. 

If you already know the starting and ending positions of a line, you can 
simplify drawing it with the word vector. 

VECTOR ( X]\y1\x2\y2~ I draws line between xl,y1 and x2,y2 ) 

For example (try it both ways): 

tlOUE.TO 100 100 LINE. TO 

is the same as: 

100 100 UECTOR 

If you only want to display a single dot, you can use the word DOT. DOT 
expects the x and y coordinate of the dot you want to display. Try displaying 
a few dots by executing: 

CLEAN 

20 20 OOT 

10 10 DOT 

30 50 DOT 

-10 35 DOT 



In MacFORTH, it is easy to define your own shapes. For example, here's a 
definition to draw a small box (you may want to edit this definition into a 
block and then load it): 

: BOX ( — I drai»3 a square on the screen ) 
10 10 nOUE.TO -10 10 DRAU.TO 
-10 -10 DRAU.TO 10 -10 DRRU.TO 
10 10 DRRU.TO J 

Now try it out by executing: 
CLERN BOH 

Feel free to modify the definition for BOX to create some graphics shapes of 
your own. You may want to increase the size of the box, or make a diamond, or 
whatever... 
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Pen Size and Shape 

The pen is rectangular in shape, and has a user-definable width and height. 
The default size ( reset by GINIT ) is a 1 by 1 bit square; the width and height 
can range from 0, (no pen show), all the way up to 32,767, 32,767 (a very, 
very thick pen). If either the pen width or the pen height is less than 1 the 
pen will not draw on the screen. 

You can modify the size of a pen by specifying its width and height in terms 
of dots to the word PENSIZE. For example, 
5 10 PENSIZE 

would specify a pen 5 dots wide and 10 dots high. To see what effect this 
has, try a few examples: 

CLEAN 

I 1 PENSIZE 100 100 DOT 

5 10 PENSIZE 50 50 DOT 

1 1 PENSIZE -50 -50 UECTOR 

10 3 PENSIZE 100 -100 UECTOR 

CLEAN 

1 1 PENSIZE DOX 

CLEAN 

1 5 PENSIZE BOH 

CLEAN 

5 1 PENSIZE BOX 

CLEAN 



The pen appears as a rectangle with its top left corner at the pen location; it 
hangs below and to the right of the pen location. You can see this by 
executing: 

10 10 PENSIZE DOT 

Think of the coordinate plane as a grid. Individual dots are separated by the 
lines of the grid. As the pen moves across the grid, only dots below and to the 
right of the pen which fall within the pen size rectangle are affected by the 
pen. 



Graphics Results Page 6 - 11 June 4, 1984 



Pen Mode and Pen Pattern Characteristics 

The pen mode and pen pattern characteristics determine how the bits under 
the pen are affected when lines or shapes are drawn. The pen pattern is a 
pattern that is used like the "inl<" in the pen. Five patterns are predefined: 
(WHITE, LTGRAY, GRAY, DKGRAY, BLACK). Try a few examples: 

CLEAN 

10 10 PENSIZE 

GRfiV PENPflT 

-100 100 -10 10 UECTOR 

DKGRflV PENPflT 

-120 100 -20 10 UECTOR 



For fun try: 
CLEAN 

CREATE <BRICKS> 
HEK 808080FF , 



080808FF , DEC I URL 



CLEAN 20 20 PENSIZE 

<BRICKS> PENPflT 

10 10 100 100 UECTOR 

Some of the other patterns that we have worked with Include: 



HEX 






CREflTE <SPIRflL> 


00FE02Ffl , 


8flBfl82FE , 


CREflTE < CHECKS > 


CCCC3333 , 


CCCC3333 , 


CREflTE <BIG. CHECKS) 


FOFOFOFO , 


OFOFOFOF , 


CREflTE <SIGnflS> 


007C4420 , 


1020447C , 


CREflTE <UEflUE> 


F8742247 , 


8F1 72271 , 


CREflTE <nflflBLES> 


77898F8F , 


7798F8F8 , 


CREflTE <UflFFLES> 


BFCOBFBF , 


BGBOBOBO , 


DECmflL 







As you can see, the pen pattern is used to fill in the bits that are affected by 
the drawing operation. 

Pen Mode 

The pen transfer mode determines how the pen pattern is to affect those dots 
which occur under the pen lines or shapes drawn. When the pen draws, 
QuickDraw first determines what bits of the bit map will be affected and 
finds their corresponding bits In the pattern. It then does a bit-by-bit 
evaluation based on the pen mode, which specifies one of eight boolean 
operations to perform. The resulting bit is placed into its proper place in 
memory. 
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The word PENMODE allows you to specify the current pen mode. Choose the 
pen mode from one of the following constants (each mode specified below is 
represented by a MacFORTH constant of the same name): 





Dot was 


Dot was 


Mode 


Black 


White 


PflTCOPV 


Force Black 


Force White 


PflTOR 


Force Black 


No Change 


PflTXOR 


Invert 


No Change 


PflTBIC 


Force White 


No Change 


NOTPflTCOPV 


Force White 


Force Black 


HOTPflTOR 


No Change 


Force Black 


NOTPRTXOR 


No Change 


invert 


HOTPRTBIC 


No Change 


Force White 



For each type of mode, there are four basic operations — Copy, Or, Xor, and 
Bic. The Copy operation simply replaces the dots in the destination with the 
dots in the pattern , "painting" over the destination without regard for what 
is already there. The Or, Xor, and Bic operations leave the destination dots 
under the white part of the pattern or source unchanged, and differ in how 
they affect the dots , thus "overlaying" the destination with the black part of 
the pattern . Xor inverts the dots under the black part. Bic erases them to 
white. 

Each of the basic operations has an alternate form in which every pixel in the 
pattern is inverted before the operation is performed. Each mode is defined 
by name as a constant in MacFORTH, e.g. (PATCOPY) . The best way to 
understand each mode is to experiment with them. Try the following 
examples to start with, and then try some of your own: 

CLEAN 

<BRICKS> PEHPRT 

PflTXOR PEHttODE 

20 20 PENSIZE 

100 -100 UECTOR 

BLflCK PEHPRT 

4 50 -50 UECTOR 
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Text Output 

MacFORTH allows you to output In any of the available text fonts, styles, 
modes, or sizes available on the Macintosh. Text drawing does not use the 
pensize pen pattern or pen mode, but It does use (and modify) the pen location. 
Each character Is placed to the right of the current pen location, with the left 
end of its base line at the pen's location. The pen is moved to the right to the 
location where it will draw the next character. Enter: 
6INIT CLEAN 
100 100 DRflU.TO 

All text drawn on the screen is drawn by QuickDraw. As a result, when the 
word DRAW.TO was echoed back to the user as it was typed in, the current 
point advanced and was left at the end of the text. The line was then drawing 
from that point to 100 100 (from the center of the window). 

Text echoed back to MacFORTH Is a special case, and only effects graphics 
drawn interactively In the MacFORTH window. When a carriage return or line 
feed is output, MacFORTH determines where to put the next line of text. Text 
advances down along the QuickDr^ native Y coordinate until the next line 
would be partially off of the window. MacFORTH then scrolls the window up 
to make room for the new line. Enter: 

CLEAN 
100 100 nOUE.TO ." Now is the line " 

-100 -100 nOUE.TO 5 . 

To move text around the screen, use MOVE.TO and then ouput the text. If you 
attempt to output a line feed at a point which is not currently In the window, 
MacFORTH will force it back onto the screen. This Is so that all error 
messages will appear on the display. 

Any text which occurs within a window Is drawn according to the currently 
specified font, style, transfer mode and size. QuickDraw can draw characters 
as quickly and easily as It draws lines and shapes, and in many prepared fonts. 



Character Font 

A character font Is defined as a collection of bit images: these images make 
up the individual characters of the font. The characters can be of unequal 
widths. A font can consist of up to 256 distinct characters, yet not all 
characters need be defined in a single font. Each font contains a missing 
symbol to be drawn In case of a request to draw a character that is missing 
from the font. Each font Is assigned a specific reference number. If you have 
deleted any fonts from the MacFORTH disc (as explained in the Macintosh 
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Users manual provided with your computer), they won't be available from 
MacFORTH. The word TEXTFONT allows you to specify the current text font. 
Choose the text font from one of the following values (no MacFORTH constants 
are provided for the text fonts): 



Font Value 

System (bold faced Geneva) 

Application 1 (New York) 

New York 2 

Geneva 3 

Monaco 4 (fixed space — the default MacFORTH font) 

Venice 5 

London 6 (Gothic) 

Athens 7 

San Francisco 8 (ransom notes) 

49'ER ROP 
^ NORtH TAHOE HIGH SCHOOL 

P. O. BOX 5099 

For example, those of you who are hook^A:^Q'Svfi/S^ofic4 Sww?^i11 
recognize: 

CR 8 TEXTFONT ." Have your goldfish^ send cash or tartar sauce" 



Toronto 



To return to the normal MacFORTH system font execute: 
4 TEXTFONT 

To read the value of the currently selected textfont, execute: 
GET. TEXTFONT . 



Text Style 

The text style controls the appearance of the font. The following styles are 
available: bold, italic, underline, outline, shadow, condense, and extend. You 
can apply these either alone or in combination. Most combinations usually 
look better on a larger character size. 

If you specify bold, each character is repeatedly drawn one bit to the right an 
appropriate number of times for extra thickness. 



/ta//c adds an italic slant to the characters. Character bits above the base 
line are skewed right; bits below the base line are skewed left. 
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Underline draws a line below the base line of the characters, if part of a 
character descends below the base line (1e: p) the underline Is not drawn 
through the dot on either side of the descending part. 

You may specify either outline or shadow. Outline makes a hollow outlined 
character rather than a solid one. With shadow, not only Is the character 
hollow and outlined, but the outline Is thickened below and to the right of the 
character to achieve the effect of a shadow. If you specify bold along with 
outline or shadow, the hollow part of the character Is widened. 

Condensed and extended affect the horizontal distance between all 
characters, including spaces. Condensed decreases the distance between 
characters and extended Increases It. 

The word TEXTSTYLE allows you to specify the current text style. Choose 
the text style from one of the following constants (each style listed Is 
represented by a MacFORTH constant of the same name): 



Style m* 


Hex Value 


PLAIN n/a 





BOLD 


1 


ITRLIC 1 


2 


UNDERLINE 2 


4 


OUTLINE 3 


8 


SHRDOU 4 


10 


CONDENSED 5 


20 


EXTENDED 6 


40 


For example: 




BOLD TEXTSTVLE 




or 




BOLD UNDERLINE + TEXTSTVLE 





To read the current text style, execute 
GET. TEXTSTVLE . 

For example, to enhance the current text style with bold face, you would 
execute: 

GET. TEXTSTVLE BOLD + TEXTSTVLE 

To reset the text style to the default (plain setting) enter: 

PLAIN TEXTSTYLE 
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Text Mode 

The text mode controls the way characters are placed on a bit image. It 

functions much like a pen mode: when a character is drawn, QuickDraw 

determines which bits of the bit image will be affected, does a bit-by-bit 

comparison based on the mode, and stores the resulting bits into the bit 

image. 

The word TEXTMODE allows you to specify the current text mode. Chose the 
text mode from one of the following constants (each mode listed is 
represented by a MacFORTH constant of the same name): 



SRCCOPV 


(source copy) 


SRCOR 


(source or) 


SRC»OR 


(source exclusive or) 


SRCBIC 


(source bit clear) 



The best way to understand each text mode is to experiment with each. The 
default text mode is SRCXOR. Try the following examples to get started, then 
continue with a few of your own: 

SRCHOR TEXinODE ( be sure ltd the default) 

PAGE 

100 100 nOUE.TO ." HELLO" 

(press Return an extra time here to avoid overwriting the previous line) 

101 101 HOUE.TO ." HELLO" 

(again, press Return a few times to avoid overwriting the previous lines) 
SRCCOPV TEXTnODE 
100 100 nOUE.TO ." HELLO" 

Remember to return to the default text mode when you finish experimenting 
by executing: 

SRCXOR TEXinODE 
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Text Size 

The text size specifies the type size for the font in points ("points" here is a 
printing term meaning 1/72 inch). Any size may be specified. If the 
Macintosh Font Manager does not have the font in a specified size, it will 
scale a size it does have in order to produce the size desired. A value of 
directs the Font Manager to select the size from among those it has for the 
font; it will choose whichever size is closest to the system font size (12 
point). 

The word TEXTSIZE allows you to specify the text size. For example, to set 
the text size to be 20, you would execute: 

20 TEXTSIZE 

You can read the current text size by executing 
GET. TEXTSIZE . 

Here are a few examples to try: 
34 TEXTSIZE 

21 TEXTSIZE 
5 TEXTSIZE 
10 TEXTSIZE 

and finally, return to the default text size by executing: 
12 TEXTSIZE 

You can see that when you increase the size of the font, it overwrites letters 
on previous lines. This is due to the line height for output, explained next. 



Line Height 

The line height determines how far to advance down the page or scroll up 
when a linefeed is encountered. Line height should normally be a little larger 
than the text size (usually 3 points). 

The word LINE.HEI6HT allows you to specify the line height, 
GET.LINE.HEIGHT returns the current line height. Here are a few examples 
to try: 

15 LINE. HEIGHT 12 TEXTSIZE ( the default ualuee) 

20 LINE. HEIGHT 

30 LINE. HEIGHT 

15 LINE. HEIGHT 

Execute GINIT to restore text font, size and line height. 
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Moving the Origin 

MacFORTH allows you to move the origin for graphics output around on your 
window. As you have already seen, XYAXIS draws the xy axis around the 
center of the coordinate system. Execute 

PAGE 

CENTER 

CRRTESIRH ON 

XVflXIS 

and you'll see the xy axis drawn in the center of your window. You can also 
select the upper and lower left corner of the window as the origin. Try. 

PAGE 

LOUER.LEFT XVRXIS 

and you'll see the xy axis (only the upper right quadrant) displayed in the 
lower left corner of your window. Now try: 

PRGE 

UPPER. LEFT XVflXIS 

and you'll see the xy axis (only the lower right quadrant) displayed in the 
upper left corner of your window. 

From any of these new origins, you can draw graphics just as you did from the 
center of the window. As before, only those points that are inside the bounds 
of the window will be displayed. 

You can take moving the xy origin one step further and position it anywhere 
(inside or outside the window). The word XYOFFSET allows you to express 
the offset from the upper left corner of your window in native QuickDraw 
coordinates for your xy origin. For example, to position your origin 150 dots 
from the left and 75 dots from the top of your window (the content region), 
you would execute: 

150 75 XVOFFSET 

Now verify this by executing: 
XVRXIS 

Try out your new origin location by executing: 
PRGE 
HVRHiS 
100 -100 UECTOR 

and you can see that the origin has indeed been moved. 
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QuickDraw Shapes 

QuickDraw supports a number of predefined shapes: 

Rectangles 

Ovals (includes circles) 
Rounded Corner Rectangles 
Arcs (includes wedges) 

Each shape may be FRAMEd, PAINTed, CLEARed, INVERTed or PATTERNed. 

The outlines of FRAMEd shapes are drawn with the current pen size, shape 
mode, and pattern. As the pen traces just inside the boundaries of the shape, 
dots to the right and below the pen (within the pen size) are modified. The 
pen location is not affected. 

Dots within the boundaries of PAINTed shapes are filled with the current pen 
pattern and mode. The pen location is not effected. 

Dots within the boundaries of CLEARed shapes are set to the background 
pattern in pattern copy mode. 

Dots within the boundaries of INVERTed shapes are toggled. Dots that were 
black become white and white dots become black. 

Dots within the boundaries of PATTERNed shapes are filled with the supplied 
pattern in pattern copy mode. 



Rectangles 

Rectangles are defined by two points at opposing corners. For example: 

GINiT PR6E 

50 50 200 200 FRflriE RECTANGLE 
200 100 100 200 INUERT RECTANGLE 
CRRTESIAN ON 

CENTEA PAGE 

XVAXIS 

-100 -100 100 100 GRRV PRTTERN RECTRNGLE 

if you still have bricks around, try: 
PAGE 
-130 -200 130 -100 <BAICICS> PATTEAN AECTANGLE 
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(If you have forgotten <BRICKS>, execute: 
HEK 

CREATE <BRICKS> 808080FF , 080808FF , 
DECmRL 

and then try the previous example again.) 

The stack arguments for a rectangle are: 
( X1\y1\x2\y2\[pattem]\mode -- ) 

Notice the top two stack items. The pattern parameter is optional. This 
convention holds true for the standard QuickDraw patterns, if you use one of 
the standard modes, you don't specify a pattern. Standard QuickDraw modes 
are: 

FRflOE PRINT CLERR INUERT 

(as explained in the beginnning of this section). In the previous example, to 
draw a framed rectangle, you executed: 
50 50 200 200 FRRhE RECTRHGLE 

If you use a pattern (like WHITE, GRAY, DKGRAY, BLACK, or one you have 
created ~ like the <BRICKS> example), you need to supply the pattern 
address and specify the mode as PATTERN. In the previous example, to draw 
a gray rectangle, you executed: 

-100 -100 100 100 GRRV PATTERN RECTRNGLE 



Ovals 

Ovals are drawn within a specified rectangle. A square rectangle results in a 

circle. For example: 

CLERN 

200 100 INUERT OURL 

<BRICKS> PENPRT 

-20 -20 PRINT OURL 

BLRCK PENPRT 

-150 -150 100 100 FRROE OURL 

The arguments to an oval are the same as those to a rectangle. 
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Rounded Corner Rectangles 

A rounded corner rectangle is specified by a rectangle and the height and 

width of an oval which describes the corners. 

For example: 
CLEAN 

50 50 120 120 20 10 iNUERT RRECTRNGLE 
-50 -50 20 20 5 5 FRROE RRECTRHGLE 

The stack arguments for a rounded rectangle are 

X 1 \y 1 \x2\y2\oval width\ova1 height\[pattern]\mode — 

The oval width and height specify the oval the corners of the rectangle lie 
within. If this seems confusing, experiment with these two values on a 
rounded rectangle a few times — a picture really is worth a thousand words! 



Arcs and Wedges 

Arcs are specified by an enclosing rectangle, and the starting angle of where 
the arc begins and the arc angle of the extent of the arc. The angles are 
treated modulo 360 and may be expressed in positive or negative degrees. A 
positive angle proceeds clockwise, a negative angle, counter clockwise. As 
with the rounded rectangles, this may seem confusing at first, but after 
experimenting with a few makes them much clearer. 

While you are experimenting (after you try the examples below), remember: 
Zero degrees is 12:00 
90 (or -270) degrees at 3:00 
1 80 (or - 1 80) degrees at 6:00 etc. 

Arcs use the following stack arguments: 

( X 1 \y 1 \x2\y2\start angle\arcangle\[pattern]\mode ~ ) 

For example: 
CLERH 

5 5 PENSIZE BLACK PEHPRT 
20 20 100 100 90 120 FRAHE ARC 
-100 -100 100 100 -45 240 GRRV PRTTERN ARC 
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Relative Line Drawing 

Frequently, groups of lines and dots are more related to each other than to 
their position on the screen. For example, the relationship between the lines 
that make up a particular character make more sense described in terms of 
each other. If the starting point is moved, then all relative lines and points 
can be redrawn without converting all of the points to the new location. For 
example: 

CLEAN 

: RBOX ( — I draw the aides relative to eachother ) 

5 5 RnOUE -10 RDRRU 

0-10 RDRRU 10 RDRRU 

10 RDRRU ; 

1 1 PEHSIZE PRTCOPV PEHnODE 
20 20 nOUE.TO RBOX 
40 30 nOUE.TO RBOX 



In fact, here's a definition to draw a symbol for FORTH (you may want to edit 
this definition into an empty block in your work file): 

) 



4TH ( — 1 draw an abstract syiibol for FORTH 


50 RHOUE 


-20 RDRRU 


-30 RHOUE 


40 RDRRU 


-20 RI10UE 


-40 RDRRU 


-20 RHOUE 


40 RDRRU 


-30 RHOUE 


-20 RDRRU 


100 RDRRU 


i 



Now move to any position and draw it. For example, try: 
CLEAN 

10 10 PENSIZE 
100 100 HOUE.TO 4TH 

1 1 PENSIZE 

HOUE.TO 4TH 

CLEAN 
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Scaling to User Coordinates 

liacFORTH allows you to scale your drawings to arbitrary user coordinates. 
You can think of "scaling" as expressing values in terms of a percentage of 
another value. The word XYSCALE allows you to set the scale for both the x 
andy axis. The default xy scale is 100,100. Try a few examples to illustrate 
this; 

For example: 

CLEflH XVflXIS 

100 50 XVSCfiLE 

10 10 nOUE.TO 4TH 

100 200 XVSCflLE 

10 10 nOUE.TO 4TH 

-50 -50 10 10 GRflV PATTERN RECTANGLE 

100 100 KVSCALE 

If you wanted to draw the dimensions of a plot of land, expressed in feet, how 
would you map this to a Macintosh window? If the window is 100 x 100 dots 
and the maximum dimension of the plot of land was 500 feet, you could set 
the scale to: 

20 20 HVSCALE 

and enter the coordinates in feet (each dot equals 5 feet). MacFORTH will 
automatically scale the data and display it for you. 



Rotate to User Coordinates 

MacFORTH also allows rotation of the coordinate system around the origin. By 
temporarily offsetting the origin, other objects may be rotated. The word 
XYPIVOT allows you to set the angle of rotation (in degrees) for the xy axis. 
For example, try rotating the 4TH symbol 30 degrees: 

PAGE CENTER 30 XVPIUOT 

XVRXIS 

50 50 100 100 UECTOR 

Now try: 

XVPIUOT 

XVAXIS 

50 50 100 100 UECTOR 

and you can see how the first line and axis was rotated 30 degrees. 
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Here's a definition to spin the 4TH symbol by just changing the pivot: 
: SPIN ( — I apin the 4TH synbol ) 
PAGE PflTXOR PENhODE 
CENTER CRRTESIRN OH 360 
DO I HVPIUOT 

nOUE.TO 4TH nOUE.TO 4TH 
3 +LOOP i 

By simply rotating the xy axis, you were able to rotate the 4TH symbol 
without modifying the word 4TH itself. Now try: 

5 5 PEHSIZE SPIN 

100 200 XVSCRLE SPIN 

200 100 XVSCRLE SPIN 

Remember, only user defined shapes are rotated. 



Integer Trig Functions 

Included in the MacFORTH graphics are two integer trig functions: sine and 
cosine. The words SIN and COS each convert an angle, expressed in degree, 
into the angle's sine or cosine scaled up by 10,000. For example, the phrase 

45 SIN . 7071 ok 

tells us that the sine of a 45 degree angle is .7071 (.7071 times 10,000 is 
7071). 

Define a word to plot one complete cycle of a sine wave. Since the input to 
SIN is an angle, we can set up a D0...L00P that runs from to 360, and use the 
index as the argument for SIN. This will return all the results from -10,000 
to +10,000, since SIN is scaled up by a factor of 10,000. If our window is 
only 200 x 200, you clearly cannot fit a full scale sine wave on the display. 
By scaling the data, however, it will easily fit. Try the following example: 

: URUE ( — I draw a scaled sine wave ) 
-1000 DUP SIN nOUE.TO 
1000 -1000 DO I I SIN DRRU.TO LOOP 

Now try: 

6INIT CLEAN 
PRIOR PEHnODE 
10 1 XVSCRLE URUE 
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Drawing to Other Windows 

Anything that can be done in the graphics system window can be done in 
another window. ( Resize MacFORTH window to a wide rectangle at the bottom 
of the screen lil<e you did in the Getting Started chapter — for figure 4.2). 
First, create a new window: 
NEU.UINOOU ERSEL 

40 40 200 350 ERSEL U. BOUNDS 
" ERSEL " ERSEL U. TITLE 
ERSEL RDD.UiNDOU 

Now clicl< in the MacFORTH window to continue. The following definitions are 
used as a shorthand method for specifying the current window (your 
fingertips will thank us). 

: >E ( — I select Easel wlndot» ) ERSEL UINDOU ; 

: >I1 ( — I select llacFORTH window ) SVS.UIHDOU UINDOU j 

Now, resize the MacFORTH window so that both it and the EASEL windows are 
visible. Then try the following examples: 

>E GINIT CENTER XVRXIS >I1 

>E 10 10 50 50 GRRV PRTTERN RECTRNGLE >I1 

! TUIST ( — ) 

GINIT CENTER CRRTESIRN ON 

360 DO I XVPIUOT nOUE.TO 50 50 DRRU.TO LOOP ; 

>E TUIST >n 

(Try some examples of your own. Remember pulling down ABORT in the 
options menu or entering the Command A keystroke will return you to the 
MacFORTH system window.) 



Finding Out Whafs There 

The word GET.PIXEL lets you find out the state of any dot on the screen. 
Given an x,y coordinate, GET.PIXEL returns a true flag if the dot at that 
coordinate is black, a false flag otherwise. The x,y coordinates are expressed 
in native Quickdraw coordinates relative to the upper left corner of the 
screen. For example, to determine if the dot at 100,100 is on, you would 
execute: 

100 100 GET.PIXEL 
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Demo Programs 

We have included some demo programs on your system disc. To load them, 
execute 

INCLUDE" Deiio Blocks" 

(or, you could double click the Demo Blocks icon from the finder). The demo 
programs are provided in source form so you can see the techniques used. 
Feel free to examine the demos (and make changes if you like). Have fun! We 
certainly did when we wrote them! To edit the demo source code, execute: 
USE" Deno Blocks" 

and then edit whichever block you like. Block 1 of the file will give you a 
good idea of where specific demos are located. 
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Overview 

MacFORTH allows you to define and control menus easily. You can specify the 
order of the menus on the menu bar, their titles and the items in each menu. 
Menu items can be selected via the mouse or command keys, disabled, 
highlighted, deleted, or even have their function changed. 

This chapter discusses how to create, activate, de-activate and delete menus 
from the menu bar. Using MacFORTH, you can create and use up to 31 menus 
simultaneously, each having up to 16 items; however, ten to twelve items per 
menu are all that will usually fit. 



Menu Example: 

In order to simplify the presentation of this material, try the following 
example first. It creates and displays a sample menu, showing how easily 
menus can be defined. You may find it easier to edit this code into a blank 
block and then load it . That way if you make a typing error you don't have to 
re-type the whole example. 

10 CONSTANT EXflNPLE ( for "example menu" ) 

: HV.HENU ( — I menu creation ueing menu i.d. 10 ) 
" Ny nenu " EXflflPLE NEU.NENU ( create the menu ) 
( append the i terns to the list: ) 
" Item 1<B<U;ltem 2/2; Item 3<l(" EXflllPLE 
APPEND. I TEnS 

DRAU.tlENU.BAA ( draw the menu bar ) 

( define the action to take place ) 
EXAMPLE HENU.SELECTION: HILITE.nENU 



CASE 1 OF 


CR ." Item 1 Selected!" 


ENDOF 


2 OF 


CR ." Item 2 Selected!" 


ENDOF 


3 OF 


CR ." Item 3 Selected!" 


ENDOF 


ENDCASE ; 






nV.flENU 







I 

Now try each of the items in "My Menu" by selecting them with the mouse (or 1 

as shown for item 2; "command 2" ~ hold down the command key and press 2). 
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Menu List 

The menus displayed by MacFORTH are maintained in a "menu list." Each entry 
in the list is a menu id (a number assigned to a menu) and its position in the 
list determines the order of the menus in the menu bar. Note that this list is 
not maintained in numeric order, but in the order of display in the menu bar. 

There are 31 entries in the menu list, allowing you to create and display up to 
31 menus using MacFORTH. 



Menu Creation 

The word NEW.MENU creates a new menu and inserts it into the menu list. 
NEW.MENU is used in the following form: 

<menu insertion point> <"menu title"> <menu id> NEW.MENU 

So, in our example, we created a new menu, inserted it at the end of the menu 
list, called it "My Menu" and assigned it menu number 10 with the phrase 
(remember, EXAMPLE is a constant with value 10): 

" My Menu " EXAMPLE NEW.MENU 



Menu Insertion Point This is the menu id that the newly defined menu is to be 
inserted before in the menu list. Specifying the menu insertion point of is 
a special case: it means that you want the menu to be inserted at the end of 
the menu bar. 



Menu ID The menu id is any number from 1 to 31 that you choose to refer to 
your new menu as. We recommend that you use a CONSTANT for your menu id's 
for later reference to the menu (like we did with EXAMPLE). You can choose 
any number you like, but we recommend that you use numbers greater than 10 
in order to avoid possible conflicts with system menus. In case of a conflict, 
the system will use the first menu it finds with the menu id given. 



Menu Title The title you choose for your menu is a string of up to 
approximately 80 characters (as long as it fits on the screen). You should use 
concise, meaningful names for your titles. 
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Menu Items 

Each of the available selections in a menu is referred to as a "menu item." The 
items in "My Menu" ("Item r',"ltem 2" and "Item 3") were appended to "My 
Menu" with the word APPEND.ITEMS used in the following form: 
<"item list"> <menu id> APPEND.ITEMS 

In our example, the phrase 

" Iten 1<B<U;lteB 2/2;lteiB 3<l(" EXflllPLE APPEND. ITEHS 

passed the item list (the quoted string) to APPEND.ITEMS for menu id 10 
(using the constant EXAMPLE). 



Item List The item list from our example may seem strange at first, but 
take a closer look. You can see the menu items listed ("Item 1", 2 and 3), 
which contain some special character suffixes. The following are special 
characters used as suffixes and cannot be specified as part of an item in the 
item list: 



Special 
Character 



Meaning 
Separates items in the list (ie: " Item 1;ltem 2;item 3" ). 



highlights the preceding item according to the character 
following <. The available highlight characters are: 

B for Bold (letters must be uppercase) 

I for Italic 

Of or Outline 

s for Shadow 

U for Underline 
(ie: " Item l<B<U;ltem 2<0;" ) 

Disables the preceding item, displaying it in grey. 
The item cannot be selected until it is enabled, 
(ie: " Function 1; Function 2(; Function 3(;" ) 



Assigns the key immediately following the / as the 
command key sequence for that menu item, 
(ie: " Attack/ A;Retreat/R;" ) 

Precedes the item with the character immediately 
following the I . (ie: " Fire!**;" ) 



Menus 



Chapter 7-4 



June 4, 1 984 



Now, using the above table, let's go back and look at the item string again. 
The first item: 

Item 1<B<U; 
specified the string "Item 1" as the menu item and made it bold faced, 
underlined. The second item: 

Item 2/2 
specified the string "Item 2" as the menu item and assigned the command key 
2 to it. When a "command 2" key is pressed (both the command key and the 
specified key held down simultaneously), Item 2 will be executed. The third 
item: 

Item 3<l( 
specified the string "Item 3" as the menu item and italicized it. The "(" 
disabled the item, preventing you from accessing it with the mouse. 



Special Strings You can display the Apple logo (apple with a bite) or a check 
mark, or any of the special characters, or any of the displayable characters on 
the Mac by creating a string and modifying it directly. For example, the Apple 
logo is character 20 (decimal) (a check mark is decimal 18). Try finding that 
key on the keyboard! (You can't, it doesn't exist.) To create a string with the 
apple in it you could execute something like: 

CRERTE RPPLES / X" 20 fiPPLE$ 1+ C! 

Or, for this example, you might try 

CREATE APPLES 1 C, ( for the count ) 20 C, (logo character ) 

You could then use APPLE$ in your menu defintion in place of the quoted 
string: 

RPPLES EXRhPLE RPPEND.ITEnS 

Separating Menu Items You can separate items in a menu with a horizontal 
bar by using a "-" character and disabling it as an item. For example , the 
string 

" Iteii l;-(jlteBi 2" <ii!enu «> RPPEHD.ITEttS 
passed to APPEND.ITEMS would separate Item 1 and Item 2 with a line. 

Displaying the Menu 

DRAW.MENU.BAR displays the new menu bar. Your menu is now active and 
ready to be used just like any other menu. If you are adding several menus, 
use DRAW.MENU.BAR after you have created and inserted the menus in the 
menu list to avoid having the menu bar flash each time a menu is added. 
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Menu Item Selection 

The word MENU.SELECTION: determines what action is taken when an item 
is selected in your new menu and is used in the form: 

<menu id> MENU.SELECTION: oction to take> 

Where the menu id is the id you assigned to the menu. When an item is 
selected, the item number of the selection is passed to the code following 
MENU.SELECTION: for execution of the appropriate action. 



Menu Item Numbers Each menu item is assigned a number when it is appended 
to the menu. The numbers start at 1 and are incremented by one for each 
item. For clarity, in our example, we numbered the items according to their 
item number. This means that our "Item 1" selection is actually item number 
1 , "Item 2" is item number 2 and so on. When an item selection occurs, this is 
the number which determines the action to take. 



Menu Item Execution When a menu item is selected, the code immediatly 
following MENU.SELECTION: for that menu is executed with the item 
number on the stack. The code executed is usually a CASE statement which 
tests the value on the stack and executes the appropriate code. 

To make this more clear, let's examine what happened when you touched down 
on Item 1 in "My Menu." The system saw a mouse click on menu item one and 
passed control to the MENU.SELECTION: code for menu 10 (which was defined 
with the EXAMPLE MENU.SELECTION: ... phrase). The code for menu 10's 
menu selection is the following case statement: 



HtLITE.nENU 








CASE 1 OF 


CR 


." IteB 1 Selected!" 


ENDOF 


2 OF 


CR 


." Ilea 2 Selected!" 


ENDOF 


3 OF 


CR 


.'' Item 3 Selected!" 


ENDOF 


ENDORSE 









which executed case 1 of the statement and returned to what you were doing 
before the mouse click occurred. The items in a menu are executed 
transparently, returning immediately to what was executing before the 
selection occurred. 
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Modifying Menu Execution You can modify the function of a menu by simply 
re-defining the menu selection definition. Try the following to change the 
execution of our example menu: 

: HEU.EXflnPLE. FUNCTION ( — ) 

EXflnPLE nENU.SELECTION: HILITE.NENU 
CASE 1 OF CR ." Ne» Function 1" ENDOF 

2 OF CR ." Nei Function 2" ENDOF 

3 OF CR ." Hew Function 3" ENDOF 
ENDCRSE ; 

NEU.EXflnPLE. FUNCTION 

Now try the items in "My Menu" and you'll see the new functions executed 
when you make your selections. This powerful feature allows you to change 
the function of any menu at any time. 

Modifying Menu Items 

You can modify the menu items (type style, enable/disable, add/delete check 
marks or characters, etc.) with the following functions (each function takes 
item^ and menu id, where the item* is the item number in the menu and menu 
id is the number of the menu): 

ITEM.STYLE allows you to change the style of the item. Used in the form: 

<item*> <style> <menu id> ITEM.STYLE 
where <style> is one of the following styles: 



Style 

PLAIN 

BOLD 

ITALIC 
UNDERLINE 


Value 

1 

2 
4 


SHADOW 


8 


OUTLINE 


16 



To get multiple styles, add the values together. For example, to get 
underlined shadow as the style, you would execute: 

<ite««> UNDERLINE SHRDOU + <Benu«> ITEN.STVLE 
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ITEM.MARK allows you to attach or remove a character to an item. Used in 
the form: 

<iteii«> <iiiark> <iiienu id> ITEH.riflRK 

where <marl<> is the character to append to the item. If <mark> is zero, any 
character currently appended is removed. <mark> is any valid ASCII character 
or special Mac character (ie: 20 is the Apple logo). 

ITEM.CHECK allows you to append or remove a check mark from a menu item 
based on a flag value. Used in the form: 

<iteiii«> <flag> <ii!enu id> I TEH. CHECK 

where <flag> is a boolean flag. If <flag> is -1 , a check mark is appended to 
the item, if <flag> is 0, the check mark is removed. 

ITEM.ENABLE allows you to enable or disable any item in the menu. Used in 
the form: 

<iteiB«> <flag> <Bienu id> I TEI1. ENABLE 

where <flag> is a boolean flag. If <flag> is -1, the item is enabled, if <flag> is 
0, the item is disabled. 

SET. ITEMS allows you to change the string associated with any menu item. 
<itei«> <3lring.addr> <nenu«> SET.ITEflS 



Deleting a Menu 

! 

You can delete a menu from the menu list by executing the word 
DELETE.MENU . Given a menu number on the stack, DELETE.MENU deletes the 
menu from the menu list and re-draws the menu bar, removing the menu. J 

<i!ienu «> DELETE. MENU 

It is a good idea to execute DELETE.MENU for the menu number you are about | 

to add (with NEW.MENU). This ensures that you won't inadvertently add the 

menu twice and is a good way to insure against multiple menus with the same 

number. I 

Disabling a Menu I 

You can enable/disable a menu at any time using the command MENU.ENABLE 
in the following form: I 

<flag> <nenu id> riENU.ENRBLE 

where <flag> is a boolean flag. If <flag> is true, the menu is enabled, if <flag> | 

is false, the menu is disabled. 
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Appendix A: Example Menus 

The following menu example is provided for you to use as 
templates/techniques for your menus. 

13 CONSTANT OP-HENU 
: OPTIONS.nEHU ( -- ) 

" OPTIONS " OP.nEHU NEU.NENU 

" TRflCE/T;DEBUG/D;UORDS;flBORT/fl" OP.tlENU APPEND. ITEMS 

DRAW. riENU. BAR OP.nEHU NEHU. SELECTION! HILITE.nENU 

CASE 

1 OF TRACE e HOT DUP TRACE ! 1 SUAP OP.tlENU 

I TEH. CHECK ENDOF 

2 OF DEBUG e NOT DUP DEBUG I 2 SUAP OP.ilENU 

I TEH. CHECK ENDOF 

3 OF UOADS ENDOF 

4 OF 1 ERROR" RBORTED!!" EHDOF 
ENDCflSE ; 



20 CONSTRNT EX-HEHU 
! nV.HEHU ( — ) 

EX.I1EHU DELETE. riEHU 

" Ny tienu" OP.tlENU NEU.tlEHU 

" lien 1;-(;ltei 2" EX.HEHU flPPEHD . I TEtIS 

DRRU.HEHU.BRR 

EX.tlENU tIENU.SELECTION: HILITE.tlENU 

CASE 1 OF CA ." Item 1 Selected" EHDOF 

2 OF CA ." Item 2 Selected" EHDOF 
ENDCASE : 
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Appendix B: Menu Glossary 

APPEND. ITEMS ltem$\menu id ~ 

Appends the items in the item$ to the menu specified by the menu handle 
on the stack. 

DELETE.MENU menu id - 

Deletes a menu from the menu item list and re-draws the menu bar. 

DRAW.MENU.BAR — 
Draws the menu bar. 

HILITE.MENU menu id - 

Highlights the menu whose id is given on the stack. Only one menu may be 
highlighted at a time. Special case; HILITE.MENU disables the highlight 
for the current menu. 

ITEM.CHECK item*\flag\menu id — 

Appends or removes a check mark from the item specified based on the 
boolean flag given. If true, a check mark is appended; if false, the check 
mark is removed. i 

ITEM.ENABLE item*\flag\menu id — 

Enables or disables the item specified based on the boolean flag given. If ( 

true, the item is enabled; if false, the item is disabled. 

ITEM.MARK item*\char\menu id — f 

Marks the specified item with the character given. 

ITEM.STYLE item*\style\menu id ~ P 

I] 
Sets the style for the item specified to the style given. 

MENU.ENABLE f lagXmenu id ~ ] 

Enables or disables the menu specified based on the boolean flag given. If 
flag is true, the menu is enabled, otherwise it is disabled. 



NEW.MENU title$\menu id ~ 

Creates a new menu, assigning the number and name given to the menu. 
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MENU.SELECTiON: menu id - 

Determines the action to be taken when an item is selected in the menu for 
the menu id specified. When an item is selected, the code following I 

MENU.SELECTION: for the appropriate menu will be passed the item * 

number of the selection. 
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Overview 

This chapter discusses window management using MacFORTH. By now you 
should have completed both the Getting Started and Getting Results chapters 
which introduce and give examples of windows. The Intent of this chapter is 
to provide you a quick reference guide to windows. 

The concept of windows Is very important in the Macintosh environment and 
MacFORTH allows you to control virtually every aspect of a window (or leave 
it to the default handlers). 



Defining a Window 

The command NEW. WINDOW creates and defines a new window structure for 
MacFORTH. To create a new window, simply execute NEW.WINDOW followed 
by the name you want to call the new window. For example; 

NEU.UINOOU nV.UiNDOU 

creates a new window named MY.WINDOW with the standard MacFORTH 
defaults. These defaults are: 

a.) title = "Untitled Window" 

b.) bounds = ( 1 00, 1 00) (200,300) 

c.) no close box or size box 

d.) the action of the window is to beep when an event occurs 

Use NEW.WINDOW outside of a colon definition. 

Window Components 

Title 

The title assigned to a window Is displayed in its title bar across the top of 
the window. You can choose any title you 11l<e for a window and assign it 
using the W.TITLE command during the definition of the window in the 
following format; 

" <title 3tring>" <windo« pointer> U. TITLE 
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You can also re-assIgn a title to a window with the SET.WTITLE command used 
in the following format: 

" <title strlng>" <»indow pointep> SET.UTITLE 

When SET.WTITLES is executed, the title bar of the window is immediately 
redrawn. 



Window Bounds 

To set the initial position and size of a window, use the W.BOUNDS command 

when the window is defined. Use the following format: 

<top> <left> <bottoii> <right> <window polnter> 14. BOUNDS 

The <top> <left> <bottom> and <right> values are the coordinates of the 
rectangle for the window, relative to the upper left corner of the screen. For 
example: 

100 150 300 350 nV.UINDOU U. BOUNDS 

will set the initial position of MY.WINDOW (used for example only) to be 100 
dots from the top of the screen, 150 dots from the left of the screen at the 
window's upper left corner. The lower right corner of the window is 300 dots 
from the top of the screen, 350 dots from the left of the screen. 



Window Attributes 

When a window is defined, you can set the attributes for it with the 

W.ATTRIBUTES command. The available attributes for a window are: 

a.) CLOSE.BOX gives the window a close box 

b.) NOT. VISIBLE makes the window invisible 

c.) SIZE.BOX gives the window a size box 



To set the attributes for a window when defining it, select the attributes you 
want the window to have and add them before executing W.ATTRIBUTES. For 
example, to give the window MY.WINDOW a close box and size box, you would 
execute: 

CLOSE.BOX SIZE.BOX + nV.UINDOU U. ATTRIBUTES 

when you define the window. 

Window Program 

Use ON.ACTIVATE to define the function of a window. This actually 
specifies the word to be executed when a window is activated. The default 
for this function is a word which will just beep when any event occurs within 
a window. 
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As discussed in the Getting Results chapter, when a window is activated, the 
word which is executed is passed a flag. This flag is true (-1) if the window 
was activated and false (0) if another window is activated (hence the current 
window is deactivated). This allows you to start up your program when the 
window is activated and perform any cleanup when the window is deactivated. 
It is important to check this flag as the first thing when you execute your 
program. Any programs you assign to a window should follow a template 
similar to: 

: UlNDOU.PROGRflfl ( actluate flag -- ) 
IF ( code for actluate ) 

ELSE ( code for deactit.'ate ) 
THEH ; 

If you FORGET the word which defines the function of a window, you will get 
unpredictable results when the window is activated. If you don't specify a 
word following ON.ACTIVATE (i.e. you just press return) you will get 
unpredictable results when the window is activated (most likely an address 
error trap). 



Event Handling in a Window 

The Macintosh is an event driven computer. This means that your programs 
should be aware of the events occurring when they are executing. The word 
DO.EVENTS handles this automatically for you, performing any default 
actions (resizing a window, hiding it when a close box is clicked, accepting 
keystrokes, etc.) and notifying you that the event occured. If you ignore 
events as they occur, your program will not be consistent with the Macintosh 
environment. To maintain consistency, your programs should be running an 
endless loop that checks for the occurence of events by executing DO.EVENTS 
often. 

With this in mind, you should expand the above template to be: 

: UlNDOU.PROGRfln ( activate flag — ) 
IF BEGIN DO.EUEHTS 

( code for actluate which checks the events ) 
RGRIN 
ELSE ( code for deactivate ) 
THEN ; 

The code for activation should also be aware of any events that occur by 
executing DO.EVENTS and checking the code returned against a list of any 
you care about. 
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The following MacFORTH constants contain the event codes for the most used 
events that occur: 

MacFORTH Constant Event 

MOUSE.DOWN mouse button pressed 

IN.CLOSE.BOX mouse click inside the close box 

IN.SiZE.BOX mouse click inside the size box 

Tracking the Mouse 

In the Getting Started chapter example, we presented a clear usage of 
tracking the mouse in the Finger Painting example. If you recall (if you don't 
recall the example, refer to the Getting Started chapter), FINGER.PAINT 
executed DO.EVENTS, which returned an event code. The only event we were 
concerned with in that example was when the mouse button was pressed, we 
checked the event code to see if it was equal to hK)USE.DOWN (a constant 
value for the event code of a mouse button being pressed). If it was, we went 
into a loop which ignored all events while the mouse was still down (which 
can be determined by the routine STILL.DOWN). 

The word ©MOUSEXY returns the x and y coordinates of the current position 
of the mouse. 



Closing a Window 

When a window is closed by a click in its close box, MacFORTH automatically 
hides the window from view and returns an IN.CLOSE.BOX event from 
DO.EVENTS. You don't need to be concerned with hiding the window, as it has 
already been hidden before you are notified that the close box has been 
clicked. This lets you perform any cleanup that should occur when a window 
is closed. 



Sizing a Window 

When a window Is resized by dragging its size box, MacFORTH will 
automatically handle the resizing for you and return an IN.SIZE.BOX event 
from DO.EVENTS. You don't need to be concerned with actually resizing the 
window, as it has already been resized before you are notified of the event. 
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Example 

In order to illustrate the above attributes (tracking the mouse, closing a 
window, and sizing a window), try the following example (you may want to 
edit it into a block): 



NEU.UIHDOU SHEET 

" Finger Paint Uindos" SHEET U. TITLE 

40 40 200 200 SHEET U. BOUNDS 

CLOSE. BOX SIZE. BOX + SHEET U.RTTRIBUTES 

SHEET flOD.UINDOU 



TRACE. FINGER ( — ) 
HIDE. CURSOR 

BEGIN STILL.DOUN UHILE eHOUSEXV DOT REPEAT 
SHOU. CURSOR ; 

FINGER. PAINT ( actlyate flag -- ) 
IF BEGIN DO.EUENTS 

CASE nOUSE.DOUH OF TRACE.FINGEA ENDOF 
IN. SIZE. BOX OF ." Uindow Resized!" ENDOF 
IN. CLOSE. BOX OF 7 SVSBEEP ENDOF 
ENDCASE 

AGAIN 
ELSE ." Uindow Deactiuated" 
THEN ; 



SHEET ON.ACTIUATE FINGER. PR I NT 



Handling Keystrokes 

If you want to input data from the keyboard in another window, you should 
look for keystrokes in the activate portion of your program. Input of 
keystrokes are handled differently from other events in that you can check for 
the presence of a keystroke (if one has been pressed) and get the key at any 
time in the activate loop part of the program. 
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The word 7KEYSTB0KE checks for a keystroke and returns either a false flag 
indicating no keystroke had been pressed, or a key value under a true flag if a 
key was pressed. 

Here's an example which modifies the finger painting example to include 
check for input of an "S" key for skinny mode, "M" key for medium mode, or "F" 
for fat mode: 



DO.FIHGER.KEV ( key 


VQ 


ue 


-- ) 




CASE 83 ( "S" ) OF 


1 


1 


PENSIZE 


ENDOF 


77 ( -fl" ) OF 


3 


3 


PENSIZE 


EHDOF 


70 ( "F" ) OF 


5 


5 


PENSIZE 


ENDOF 


7 SVSBEEP 










EHDCflSE : 











Now modify FINGER. PAINT to be: 

: FINGER. PRINT ( actluate flag 



-- ) 



IF 


BEGIN DO.EUENTS 










CRSE HOUSE. DOUN 


OF 


TRRCE. FINGER 


ENDOF 




7KEVSTR0KE 


IF 


DO.FIHGER.ICEV 


THEN 




ENDORSE 










RGRIN 








ELSE 

THPN 


7 SVSBEEP ." Finger 1 


'ainting Finished 


" 



SHEET ON.RCTIURTE FINGER-PRINT 



Default Event Actions 

MacFORTH executes a default operation for each event, within DO.E VENTS, 
prior to returning an event code to the user. The default operation typically 
handles all of the messy details required by the Mac User Interface and just 
returns an event code to let you know what happened. The default actions are 
summarized below for each event. 

Common to all events: If a keystroke has been received but not picked up by 
the user (via KEY) no further keystroke events are allowed until the current 
one is cleared. Type-ahead characters are thus accumulated In the event 
queue. If a Mouse.Down event occurs outside the content region of the current 
window, events 17-24 (see Events List ahead) are systheslzed to indicate a 
special Mouse.Down event. 
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The following events have special default actions: 



Event 
MOUSE.DOWN 



MOUSE.UP 
KEY.DOWN 
UPDATE. WINDOW 



Default Action 

Check for events 17-23 and if appropriate 
returns that code instead. Code of 1 indicates 
mouse down in content region of current 
window. EVENT.RECORD is copied to 
MOUSE.DOWN.RECORD. 

EVENT.RECORD is copied to MOUSE.UP.RECORD 

EVENT.RECORD is copied to keystroke array. 

begins update , passes control to window 
update token, ends update 



ACTIVATE. WINDOW passes control to window's activate token 
COMMAND.KEY simulates menu event 

beeps 



IN.DESKTOP 
IN.SYS.WINDOW 

I N.LOWER. WINDOW 
IN.DRA6.B0X 
IN.SIZE.BOX 
IN.CLOSE.BOX 



passes control to execution procedure posted 
for menu by MENU.SELECTION: 

activates lower window 

drags window 

resizes window 

hides window 
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Complete Events List 



DO.E VENTS always returns one of the following event codes: 






NULL.EVENT 


10 


NETWORK.EVENT 


1 


MOUSE.DOWN 


11 


DRVR.EVENT 


2 


mUSE.UP 


16 


COMMAND.KEY 


3 


KEY. DOWN 


18 


iN.MENU.BAR 


4 


KEY.UP 


19 


IN.SYS. WINDOW 


5 


AUTO. KEY 


20 


IN.LOWER. WINDOW 


6 


UPDATE.EVENT 


21 


IN.DRAG.BOX 


7 


DISK.EVENT 


22 


IN.5IZE.B0X 


8 


ACT IVATE.E VENT 


23 


IN.CLOSE.BOX 


9 


ABORT.EVENT 







Note: Refer to "Inside Macintosh" for the meaning of events not described in 
this chapter. 
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Appendix A: Window Glossary 



Glossary Key: 

wptr Refers to the pointer to a window record whicii contains all 
of the information about the window needed by the system. 
This value is returned by a window specifier. 

Definitions: 

@MOUSEXY — x\y 

Returns coordinates of the mouse. 

ADD. WINDOW wptr — 

Opens a window on the screen using the preset title, bounds, behind, 

type and attributes. The content region is sized for the specified 

controls. 
BS - 8 

A constant which returns the ASCII value of a backspace. 

FRONT.WINDOW -- wptr 

Returns the window pointer of the front window (which is the currently 
active window). 

GET. WINDOW -- wptr 

Returns the window pointer of the current window used for output. 



MAC.CON — addr 

Returns the address of the Mac console device table. The phrase 

MAC.CON CONSOLE ! 
directs output to the Mac console. 

MOUSE.DOWN — n 

Returns the value of a mouse down event (as returned by DO.EVENTS). 

NEW.WINDOW — «compile time» 

~ wptr <<run time» 
Defining word which creates text window specifiers. When the window 
specifier is later executed, its window pointer is returned on the stack. 

PAGE 

Clears the window and puts the cursor in the upper left corner. 
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SCREEN.BOUNDS -- addr 

Returns the address of the rectangle containing the screen boundaries. 
The rectangle coordinates are in packed 16-bit values for top, left, 
bottom, and right. 

SYS. WINDOW -- addr 

Default MacFORTH window name. This is the window presented when 
MacFORTH is active. 

TYPE addrVcnt ~ 

Outputs the specified string to the current window. 

W.BEHIND front wptrXback wptr — 

Causes the window specified as 'back wptr' to be opened behind 'front 
wptr. 

W.BOUNDS X 1 \y 1 \x2\y2\wptr ~ 

Sets the bounds of the window specified. 

W.TITLE addrXwptr — 

Places the supplied string address into the window parameter list. 
When the window is opened the title string is taken from the specified 
address. 

W.TYPE nXwptr — 

Sets the window type. The default is (document windows). 

WINDOW wptr — 

Sets the specified window as the window for output. All text and 
graphics images will be output to that window. 
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Overview 

This chapter discusses how MacFORTH interfaces to the Macintosh file 
system. Using MacFORTH, you can create, read and write any standard 
Macintosh file. This allows you to share data among applications. 

You can have up to 9 files assigned and open at a time for accessing the data 
within a file. MacFORTH supports two file types: data and program (or 
"blocks") files. The records within a data file can be one of three types: fixed 
length records, text records and virtual data files (free-format records). The 
records within a program file are fixed length records, each containing 1024 
characters. 

We refer to program files as "blocks" files because they are made up of source 
code blocks (as explained in the Editor chapter). 



File Input/Output Operation Result Codes 

For each file operation a result code is returned in the variable lO-RESULT. 
This result code allows you to check the operation to see if it completed 
successfully, and if not, why not. 

Each of the I/O result codes are listed in Appendix B of this chapter for your 
reference. If the file operation is successful, the result code is 0, otherwise 
the value indicates an error condition. This allows you to monitor the result 
of each file operation. You can then set the level of error checking from no 
checking to full error checking/re-try attempts, etc. If you aren't concerned 
with the result of the operation, ignore it. 

The word 7FILE.ERR0R is provided to handle file manipulation error 
conditions in a basic manner. It is executed immediately following a file 
operation and, if an error occurred, will abort the current task displaying the 
appropriate error message. For example if you executed the phrase ( don't try 
it now) 

1 OPEN 7FILE.ERR0R 

and the file assigned to file number 1 was not found (I/O result code -43), the 
current task would be aborted and the error message "File Not Found!" would 
be displayed. 
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File Assignment 

The Macintosh file system is based on assigning files (using their names) to a 
file number and using that number in referring to the file. In MacFORTH, we 
recommend that you use a CONSTANT value to refer to the file number to make 
your programs more readable. 

File Numbers The first thing you must do when preparing to create a new file, 
or access an existing file, is assign it a file number. MacFORTH allows you to 
access up to 9 files using file numbers 0-8. If you use a file number outside 
of the range 0-8, MacFORTH will issue the error message "Illegal File*". 

The command ASSIGN assigns a file number to a file name and is used in the 
following format: 

<"filenaie"> <file«(0-8)> ASSIGN 

For example, the phrase 

" Employee Rge" 1 RSSIGN 

would assign file number 1 to the file titled "Employee Age". As we 
mentioned above, it is a good idea to create a constant for file numbers. In 
the above example, you could execute 

1 CONSTflHT AGE. FILE 

" Employee Age" AGE. FILE ASSIGH 

Later references to the file can be made using the constant, making your 
program easier to read and understand. 

Alternate Volumes 

You can access files on another (previously mounted) volume by simply using 
the volume name as a prefix to the file name in the ASSIGN statement. For 
example, to assign the file "Employee Salary" on the volume "Employee 
Information", to file number 3, you would execute: 

3 CONSTANT SALAAV.FILE 

"Employee Informal ion: Employee Salary" SALARV.FILE ASSIGN 

When you access the file later, you will be prompted to insert the appropriate 
disk if it is not currently in the drive. 
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Displaying File Assignments 

You can display the current file assignments by executing the ?FiLES 
command. Each file number is displayed with its associated file name. A 
capitalized "0" next to the number implies the file is open. A lowercase "b" 
indicates it is a blocks file, a capitalized "B" next to a file number indicates 
it is the current blocks file. 

Opening a File 

Once you have assigned a file a file number, use the OPEN command to open a 
file for access. Use the following format: 
<file«> OPEN 

It is always a good idea to check the I/O result code after opening to be sure 
it was opened correctly. 



Displaying the Disk Directory 

The DIR command displays the disk directory of the specified drive. To 
display the directory of the disk in the internal drive, execute: 
INTERNflL DIR 

To display the directory of the disk in the external drive (if present), execute: 
EHTERNflL DIR 

The following information is presented when you use the DIR command: 
1.) volume name 
2.) number of files 
3.) amount of space available 
4.) volume creation date 
5.) volume last modified date 
6.) for each file: 

a.) file name (first 19 characters) 

b.) file attributes 

i.) "L" for locked, "-" for unlocked 
ii.) "U" for in use, "-" for not in use 

c.) file type 

d.) file size 

e.) file creation date 

f.)file last modified date 

The difference between 7FILES and DIR is: 7FILES displays the file 
assignments and DIR displays the contents of the disk. 
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MacFORTH File Types 

There are two standard types of files you will use with MacFORTH: data files 
and blocks files. Data files contain data in a free-format. Blocks files 
contain program source code in sequential fixed length records. 

From the Finder, you can distinguish between these two file types by their 
icons. Data file icons are the standard file icon used (plain rectangular 
document icons). Blocks file icons are rectangular document icons with three 
rectangles within the bounds of the icon. These rectangles represent the 
three blocks of source code you can print out on a sheet of paper using the 
word TRIAD (explained in the Editor chapter). 

You can load a blocks file from the Finder by double clicking it. When a blocks 
file is loaded in this manner, MacFORTH is loaded first, then block 1 of the 
selected file is loaded (more about this later). 



Data Files 

Data files contain data in whatever format you specify. The data can be 
stored as a virtual array with no particular format all the way up to fixed 
fields within fixed records. 



Creating a Data File 

If the file you have assigned already exists on the disk, there is no need to 

re-create it; go on to "Opening a Data File." 

Once a file is assigned, you can create it on disk with the CREATE.FILE 
command in the following format: 
<flle«> CREATE.FILE 

This command will create the file on disk and place it into the disk file 
directory as a "DATA" type file. Be sure to check the I/O result code returned 
by CREATE.FILE to be sure that the file was created correctly (ie. enough 
room on the disk, in the catalog, no naming conflicts, etc.). 
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Allocating Space in a Data File 

There are three methods you can use for allocating space for files: 

a) Use the ALLOCATE command 

b) Don't (let the system do it for you) 

c) Both a) and b) 

When you create a data file, no space is initially allocated for data in the file. 
To create some space using method a), use the ALLOCATE command to 
allocate space for the file on the disk. The space allocated is contiguous on 
the disk. ALLOCATE is used in the following format: 

<nuBber of bytes in the file> <file«> RLLOCflTE 

Suppose you wanted to allocate enough space for 100 records, each 50 
characters in length. The number of bytes needed is 5000 (100 * 50), so you 
could execute (assuming file* 5): 
5000 5 RLLOCflTE 

To create some space using method b), you can simply start writing data into 
the file. This appends data to the file, allocating space for the data as 
needed. Each time you write data into the file, the furthest write operation 
into the file sets the end-of-file pointer. You can write past the end-of-file 
pointer (and re-set it), but you can't read past it. This simply means that you 
should write data to the last position in the file you will access before trying 
to read from it. 

You can also combine both methods to create space in your file. You may want 
to start out and allocate some space in the file and as the file grows, simply 
append data to the end, increasing its size. 



Reading/Writing in a Data File 

MacFORTH supports three data file record types: fixed, text, and virtual. Each 
type has is own best use and you are free to use any type you like within an 
application. Fixed record files are the simplest and most useful, text record 
files make efficient use of disk space for text storage, and virtual record 
files are the most flexible. 

The MacFORTH file system reads and writes data records from a record buffer 
from/to a file. A record buffer is simply an area in memory that you specify 
for reading/writing records. To create a record buffer, simply allocate the 
amount of space needed for the longest record you will read or write. 
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For example, If you will be accessing data records in a file and know that the 
maximum record length is 60 bytes, you could create a record buffer by 
executing: 

60 COHSTRNT REC.BUF.SIZE 

CREATE REC.BUF REC.BUF.SIZE RLLOT 

This phrase created a record buffer called REC.BUF and allocated 60 bytes 
for It. If you create a record buffer smaller than your record size 
and read data Into it, you could crash the system. When the data Is 
read from the file. It will continue to overwrite your dictionary, so be sure to 
allocate enough space. That is why we created the constant REC.BUF.SIZE in 
the above example. When reading or writing, you can specify the size of the 
buffer as a constant to be sure you use the right size. 

You may also use the scratchpad buffer, PAD, but be sure to use a reasonable 
record size to avoid overwriting the end of the object space. 



Fixed Record Data Files 

Fixed files are made up of records of the same size. This format allows you 
to access any record In the file by its record number. The records In a fixed 
file are In sequence starting at record number through the last record in the 
file. 

Soeclfvlng Record Size After you assign a fixed file, before you can read or 
write data In the file, you need to specify the size of each record in the file. 
Use the SET.REC.LEN command in the following format: 
<iax rec 8l2e> <flle«> SET.REC.LEN 

For example, if you were using fixed record lengths of 37 in fixed file *3 
(using the constant MYFILE) you would execute: 
37 nVFILE SET.REC.LEN 

This Is the value used by the MacFORTH system when reading/writing records 
In a fixed file. If you don't specify the record size, you'll get the error 
message "Fixed Record Length = 0!" when you try to read or write records In 
the file. 



Accessing Records Once you have assigned and opened the file, and allocated 
a record buffer for the file, accessing records within the file Is simple. To 
read a record Into your buffer, you supply the buffer address, record number 
and file number to the command READ.FIXED . For example, to read record 5 
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from file ^3 (represented by the constant MYFILE) into a buffer named 
REC.BUF, you would execute: 

REC.BUF 5 nVFILE READ. FIXED 

Similarly, to write a record, you use the same format. For example, to write 
record 12 to file * MYFILE from a buffer named REC.BUF, you would execute: 
REC.BUF 12 nVFILE URITE. FIXED 



Text Files 

Text files are made up of a sequence of text (ASCII characters) records 
separated by carriage returns. This is an efficient way to store text files 
because only the space needed for the text is used (no wasted space as may be 
found in using fixed records for variable length text storage). 

Because the records in a text file are variable length, you won't know how 
long a particular record is until you have read the entire record into your 
buffer. 



Rewinding a Text File To rewind a text file (set its position pointer to point 
to the start of the file), use the word REWIND in the following format: 
<flle«> REUIND 

For example, to rewind file * MYFILE (where MYFILE is simply a constant 
containing the file number), you would execute 
nVFILE REUIHD 



Reading Records in a Text File Once you have assigned and opened the text 
file you want to use, and created a record buffer for the records, reading and 
writing records from/to the file is simple. For example, to read the first 
text record in file number MYFILE into a record buffer named REC.BUF with 
length of REC.BUF.LEN, you would execute: 

nVFILE REUIHD 

REC.BUF REC.BUF.LEN nVFILE READ. TEXT 

To read the next record in the file, you would execute: 
REC.BUF REC.BUF.LEN HVFILE READ. TEXT 

and so on. After each read operation in a text file, the file pointer is 
positioned to the first byte of the next record. Subsequent read operations 
read the next record in the file automatically. 
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What if your buffer isn't long enough for the record being read? Unlike the 
fixed record files, you can use a buffer that is shorter than the length of the 
record being read. (We recommend you use record buffer long enough to accept 
the longest text record in the file for simplicity.) Let's look at an example to 
illustrate this point. Suppose that the next record in the text file you are 
reading from is 10 characters in length, consisting of the following; 

Char*; 1 23456789 10 

Chars ; B o b Smith <cr> 

If you read this record into a buffer of length 10 or more, you will get the 
entire record and can continue. But, on the other hand, if you read this record 
into a record buffer of length, say 7, you will only get the first seven 
characters. To get the rest of the record ( "t", "h", and the carriage return), 
perform a read command just as if the rest of the record was the next record 
in the file. The read will terminate on the carriage return, so only the 3 
characters remaining will be read. 

When MacFORTH reads a text record into a buffer, it transfers characters to 
the buffer one at a time until it encounters a carriage return in the file 
("normal" termination) or until the record buffer is full. If the record buffer 
is full prior to encountering a carriage return, the file pointer is left pointing 
at the next character to be read from the current text record. Subsequent 
reads will begin at that character (just as if it were the first character in 
the record). 



Writing Records in a Text File To add records to a text file use the 
WRITE.TEXT command as follows; 

<buffer addr> <record length> <file«> WRITE. TEXT 

For example, to add the record in the buffer REC.BUF which is 10 bytes long 
(including a carriage return at the end) to file number MYFILE, you would 
execute; 

REC.BUF to fIVFiLE URiTE.TEHT 

When writing text records, you must append a carriage return to the end of 
the record (EOL). 
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Virtual Files 

Virtual files are the most flexible file format of the three types supported by 
MacFORTH. Using virtual files, you could re-write each of the existing file 
structures or create your own new file types. To MacFORTH, a virtual file is 
simply a virtual array of characters. You can manipulate this array in any 
way you like. 



Accessing Data in a Virtual File To read data within the file to a buffer, use 
READ.VIRTUAL in the following format: 

<buffer addr> <length> <flleaddp> <file«> REflD.UIRTUflL 

The only new parameter you may not recognize is <file addr>. This is the 
offset from the start of the file where you would like to start reading data. 
For example, to read 100 bytes from the file number 6 (represented by the 
constant MYFILE) starting at the beginning of the file into the record buffer 
REC.BUF, you would execute: 

REC.BUF 100 nVFILE REflD.UIRTUflL 

To read 7 bytes from the same file, starting at the 23rd element in the file 
into the record buffer REC.BUF, you would execute: 
REC.BUF 7 23 nVFILE REflD.UIRTUflL 

Writing data into the file is done in a similar manner using the word 
WRITE.VIRTUAL in the following format: 

<buffer addr> <lenglh> <file addr> <file«> URITE.UIRTUflL 

For example, to write 30 bytes of data from PAD, starting at position 100, 
you would execute: 

PflD 30 100 nVFILE URITE.UIRTUflL 



Blocks Files 

Blocks files contain program source code. Each file is made up of a sequence 
of blocks (1024 bytes) numbered from zero through the maximum block in the 
file. 



Creating a Blocks File 

If the file you have assigned already exists on the disk, there is no need to 

re-created it; go on to "Opening a Blocks File." 

Once you have ASSIGNed a file number to the file you want to use as a blocks 
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file, create the file with the CREATE.BLOCKS.FILE command in the 
following format: 

<file«> CREATE.BLOCKS.FILE 

This command will create a file on disk and place it into the disk file 
directory. Be sure to check the i/0 result code to be sure the file was created 
correctly. 



Allocating Space in a Blocks File 

When you create a new file, you don't have any room for blocks in it. To 

allocate room in the file, use the APPEND.BLOCKS command in the following 

format: 

<«of block3> <file«> APPEND. BLOCKS 

For example, to initially create space for 10 blocks in a newly created blocks 
file, (with file number represented by the constant MY.BLOCKS) execute: 
10 nV. BLOCKS APPEND. BLOCKS 

FORTH blocks are normally printed three to a page in "triads," so you may 
want to allocate space in multiples of three blocks as a convenience when 
printing (by no means is this necessary). 



Re-allocating Space Within a Blocks File 

Once you have allocated space to a blocks file, you can change the size of the 
file with the APPEND.BLOCKS command used in the following format: 
<*ofblocks> <file*> APPEND.BLOCKS 

where <*of b1ocks> is positive to add blocks, or negative to delete blocks 
from the specified blocks file. For example, to add 6 blocks to the file 
identified by the constant MY.FILE, you would execute 
6 HV.FILE APPEND.BLOCKS 

or to delete 3 blocks from that file: 

-3 nV.FILE APPEND.BLOCKS 



Accessing Program Source Code in a Blocks File 

To access the data within the file as a blocks file, you select it as the 
"current blocks file." To select a file, use the SELECT command in the 
following format: 

<file«> SELECT 
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This commanci selects the specified file as the current file for block access. 
Once assigned and opened, you can select any blocks file to be the current 
blocks file with this command. Be aware that MacFORTH does not 
discriminate what files can be used as blocks files. If you assign, open and 
select a data file as the current blocks file, MacFORTH will treat the data file 
just as if it were a block record. You are responsible for selecting the proper 
file. We recommend that you use the word "blocks" in the name of your file to 
distinguish it from other files on your disk (ie. "Graphics Blocks" or 
"Checkbook Blocks", etc.). 

When executed, SELECT saves the block buffers and the file information out 
on the disk, insuring that any unwritten data from the previous blocks file is 
saved, and then selects the specified file as the current blocks file. 

The MacFORTH word USE" is provided for convencience when you want to edit 
a blocks file. Used in the form 

USE" <flle naiie>" 

the file specified is assigned to the first available FCB, opened, and selected 
as the current blocks. For example, if you wanted to edit the "Demo Blocks" 
file, you could execute: 

" Demo Blocks" 3 RSSIGN 

3 OPEN 7FILE.ERR0R 

3 SELECT 

or, you could use 

USE" Deno Blocks" 



MacFORTH Blocks File Structure 

MacFORTH reserves the first two blocks in a file (blocks and 1 ) for a special 
purpose. Block is used as a comment block for the file and can't be loaded. 
Block 1 is used as a load block for the entire file. 

Use block to make notes about the file, current revision of the program, etc. 
This is handy for later reference. 

Use block 1 as a load block for your application. This important because when 
you open (by double clicking) a MacFORTH blocks file from the Finder, 
MacFORTH selects the file and loads block 1. 
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Including a File 

The word INCLUDE" allows you to load another blocks file. The specified file 
will be assigned , opened, and loaded (by loading block 1). You can use 
INCLUDE" from any file to load another file, then continue loading the 
original file. For example, if you had the source code to a file named 
"Checkbook Blocks", you could load it by executing 
INCLUDE" Checkbook Blocks" 

INCLUDE' may be nested . This means that a file that is being included can 
include a file itself. 

When INCLUDE" is executed, the specified file is assigned to the first 
available FCB. 



Closing a File 

When you have finished using a file, you should close it. This ensures that all 
data is written to the disk and that the file system updates all necessary 
information about the file. To close a file, simply execute the CLOSE 
command using the file number to be closed. For example, to close file* 7, 
you would execute: 
7 CLOSE 

You should always check the I/O result code when you close a file to be sure 
it was properly closed. 



Deleting a File 

To remove a file from the disk (and destroy all data contained in the file), use 
the DELETE command. Once a file is deleted, you cannot recover the data 
from it, so use this command with caution. To delete a file from the current 
disk, execute the DELETE command as follows: 
<file*> DELETE 



Ejecting a Disk 

You can eject a disk from the drive with the command 
INTERNAL EJECT 

To eject the disk in the external drive (if present) execute 
EXTERNAL EJECT 
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Mounting a New Volume 

To mount a new volume, simply eject the disk that is in the drive and insert 
the desired disk (volume). MacFORTH will automatically mount the new 
volume. 



Advanced File System Topics 

This section discusses some of the inner workings of the MacFORTH file 
system. It is intended for the advanced user. You do not need to read this 
section to use the file system. 

File Control Blocks MacFORTH uses an array for each file number used. The 
information in this array is required by the Macintosh file commands. You can 
examine and alter (at your own risk!!) any information about a file by 
examining its file control block. 

The command >FCB returns the address of the fcb array for the given file 
number. Each array is 90 bytes long. 

File Pointer The basis of the MacFORTH file system is the word POINT which 
points into a file. POINT allows you to point anywhere in a file, randomly, 
sequentially, relative to the front, back or anywhere in-between. POINT is 
used in the following format: 

<position> <position mode> <file*> POINT 



Position Modes There are four position modes for use with POINT : 

Mode Position Type 

FROM.START position relative to the start of the file 

FROM.END position relative to the end of the file 

FROM.CURRENT position relative to the current file position 

VIRTUAL position to any specified location in the file 

To clarify this point, let's look a some examples (we'll use the dummy 
constant FILE* to represent a valid file number): 

a) position at the start of the file: 

FROn. START FILE« POINT 

b) position at the end of the file 

FROn.END FILE* POIHT 
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c) position at the 17th character in the file 

17 FROfl. START FILE« POINT 

d) position 4 characters before the current position in the file 

-4 FROn. CURRENT FILE* POINT 

Note: The above three operators set the file mode to text. This means that 
the file pointer will be positioned where you specify, but until you change the 
mode (if text is not the desired mode), you will be reading and writing text 
records (terminating on carriage returns). 

You can also use the position mode VIRTUAL to point to any byte in the file. 
Using the above examples: 

a) position at the start of the file 

UIRTURL FILE* POINT 

b) position at the end of the file 

<iax « of bytes In file> UIRTURL FILE« POINT 

c) position at the 1 7th character in the file 

17 UIRTURL FILE* POINT 

d) position 4 characters before the current position in the file 

CURRENT. POSITION 4 - UIRTURL FILE* POINT 



File Names The name given to a file is any string of up to 255 characters in 
length. Invalid characters include colon (:) and double quote ("). 

Volume Names A volume name is any string of up to 26 characters in length 
and terminated by a colon (:). 



Maximum File Length For practical purposes, the maximum file size is 
limited only by the amount of available space on a disc. The absolute file size 
maximum is 15 megabytes (16,722,216 bytes). The maximum record size to 
be read at one time is 64 kilobytes (65,535 bytes), but is currently limited to 
the amount of memory available. 
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Appendix A: Example File Usage 

In order to simplify your tasl< of using the file system in your application, we 
present the following simple example as a template. The example is a simple 
system of keeping track of three people (by their last names) and their ages 
in the fixed file "Ages File". Their names and ages are: 

Name Age 

SMITH 26 

JONES 38 

WILSON 31 

and we will translate them to: 

CREATE RECl 26 C, ," SMITH " 
CREATE REC2 38 C, /'JONES" 
CREATE REC3 31 C, ," WILSON" 

(Note that we are simply placing the data into the dictionary for the purpose 
of example. This data would normally be accessed via another file or input 
directly from the keyboard.) 



Now, continue with assigning, creating and opening the file: 
1 CONSTflHT AGES. FILE 
" Ages File" AGES. FILE ASSIGN 
AGES. FILE CAEATE.FILE 7FILE.ERA0R 

AGES. FILE OPEN ?FILE.ERROR 

The buffer used to read the records into: 
8 CONSTANT AGES. REC. SIZE 
CREATE AGES_BUF AGES . REC . S I ZE ALLOT 

Set the fixed record size: 

AGES. AEC. SIZE AGES. FILE SET.REC.LEN 

Next, we'll write the records into the file: 



RECl 1 AGES. FILE 


URITE 


.FIXED 


?FILE. ERROR 


AEC2 2 AGES. FILE 


URITE, 


.FIXED 


?FILE. ERROR 


REC3 3 AGES. FILE 


URITE, 


.FIXED 


7FILE. ERROR 



(Notice that we didn't need to set the end of file pointer; it was done 
automatically by writing data at the end of the file each time. The file 
system automatically increased the file size.) 
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Here's a word which will read each record and print the information; 

: D I SPLflV. RECORD ( — I display data for the current rec) 
RGES-BUF 1+ COUNT TVPE ( display the none ) 

." is " RGES_BUF Ce . ( display the age ) 
." years old." ; 



: SHOH.RGES ( — ) 3 ( the number of recs in file ) 

DO flGES_BUF I AGES. FILE READ. FIXED 7FILE.ERR0R 

CR DiSPLRV. RECORD 
LOOP ; 

Suppose you wanted to change JONES* age to 39? 

flGES_BUF 2 RGES.FILE READ. FIXED ( read Jones' record ) 

39 flGES_BUF CI ( change the age ) 

flGES_BUF 2 RGES.FILE WRITE. FIXED ( re-write the record ) 
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Appendix B: File System i/0 Result Codes 

The following result codes are returned by the system ROM after an 
input/Output operation has taken place: 

Result 

Code Meaning 

No error. Operation completed successfully. 

-33 Directory full 

-34 Disc full 

-35 No such volume 

-36 Disc I/O error 

-37 Bad filename 

-38 Fork not open 

-39 End of fork 

-40 Position error. Tried to position before start of file. 

-41 Memory full 

-42 Too many forks - more than 1 2 forks open 

-43 File not found 

-44 Disc write protected 

-45 File locked 

-46 Volume locked 

-47 One or more files are opened 

-48 Duplicate file name 

-49 Fork already opened with read/write permission 

-50 No drive number specified 

-51 No file assigned, reference number specifies nonexistent 
access path 

-53 Volume not on-line 

-54 Locked volume can't be written to 

-55 Volume already mounted and on-line in drive 

-56 Invalid drive number - number specified doesn't match an 

existing drive 

-57 Invalid disc directory 

-58 External file system; can't recognize volume 

-59 Problem during rename 

-60 Master directory block is bad 

-61 Read/write or open permissions - writing not allowed 
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Appendix C: File System Glossary 

Glossary Key 

The following symbols and abbreviations are used in this glossary: 

Symbol Meaning 

file^ a valid file number (0-8) identifying a file 

file$ the string address of a file name 

name string address with count in first byte 

pos mode the positioning mode used for the file system 



Glossary Definitions 

"BLKS —file type 

Constant containing the BLKS file type. 

"DATA —file type 

Constant containing the DATA file type. 

"M4TH —file type 

Constant containing the M4TH file type. 

"PICT -file type 

Constant containing the PICT file type. 

"TEXT -file type 

Constant containing the TEXT file type. 

@FILE.NAME file*-file$ 

Returns the address of the file name string of the specified file. 

@REC.LEN file* — rec len 

Returns the fixed record length for the fixed record file specified. 

.FILE.ERROR error* - 

Displays the file error message for the given file error number. 

+MAX.BLK* fcb — addr 

Returns the address of the maximum block number element (32-bits) in the 
file control block. For example: 

>FCB +MAX.BLK* @ 
returns the maximum number of blocks in the blocks file with file number 
zero. 
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+REC.SIZE fcb — addr 

Returns the address of the record size element (16-bits) in the file 
control block. For example: 

0>FCB +REC.5IZE W@ 
returns the record size of the file with file number zero. 

+SCR* fcb -- addr 

Returns the address of the screen (block) number element (32-bits) in the 
file control block. For example: 

>FCB +SCR*- @ 
returns the current block number of the blocks file with file number zero. 

*FILES — n 

Returns the maximum number of files that MacFORTH allows to be open at 
one time. 

?EOF -- flag 

Returns a true flag if the end-of-file marker of the current file has been 
reached for the file that was most recently read/written. 

7FILE.ERR0R — 

Checks the value of lO-RESULT and aborts the current task, displaying an 
error message if lO-RESULT is non-zero. 

7FILES 

Displays the current file number assignments. 

70PEN file* — flag 

Returns a true flag if the file number specified is open, otherwise the flag 
is false. 

>FCB file* — fcb 

Returns the file control block address for the file number specified. 

ADD.BLOCKS *blocks\file* - 
Adds *blocks to the file. 

ALLOCATE file sizeXfile* -- 

Allocates the specified number of bytes for the specified file. 

APPEND.BLOCKS *b1ocks\file* - 

Adds/deletes blocks to/from the specified file. If *blocks is positive, 
that number of blocks is added to the file (disc space permitting). If 
*blocks is negative, that number of blocks are deleted from the end of the 
file. 
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ASSIGN file$\file*~ 

Assjgns the file name specfied to the file number specified. Sets 
lO-RESULT to if the file number was not previously assigned, 
otherwise it stores the name string address of the previous string into 
lO-RESULT 

BLOCK-FILE ~ addr 

Variable containing the file number of the current blocks file. 

CLOSE file*-- 

Closes the specified file, returning the result code for the operation. 

CLOSE.ALL 

Closes all files. 

CREATE.BLOCKS.FILE file* — 

Creates the specified blocks file on disc. The file is specified as a 
MacFORTH blocks file and can be loaded from the finder. 

CREATE.FILE file* - 

Creates the specified file on disc. 

CURRENT.POSITION file* - position 

Returns the position mode under the current position pointer into the file 
number specified. 

DELETE file*~ 

Deletes the specified file from disc. 

DELETE.BLOCKS *blocks\file* - 
Deletes *blocks from the file. 

DIR drive* — 

Displays the directory for the disc in the specified drive. Use INTERNAL 
and EXTERNAL to specify the drive. 

EXTERNAL - n 

Constant value which specifies the external disc drive. 

EJECT drive specifier — 

Ejects the disc from the specified drive. Use INTERNAL or EXTERNAL as 
the drive specifier. 

FCB.LEN - n 

Constant containing the length of an FCB. 
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FILE.TYPE file typeXfile* - 

Sets the specified file to the file type given. 

FLUSH.FILE file* - 

Writes the file control block of the file specified out to disc. 

FROM.END — pos mode 

Returns the value which specifies that positioning is relative to the end of 
the file. 

FROM.CURRENT - pos mode 

Returns the value which specifies that positioning is relative to the 
current file position. 

FROM.START ~ pos mode 

Returns the value which specifies that positioning is to take place 
relative to the start of the file. 

GET.EOF file* — *bytes 

Returns the number of bytes in the specified file. 

GET.FILE.INFO file*-- 

Reads the file information from disk for the specified file. The 
information is kept in the file's FCB. 

GET.FILE.TYPE file* ~ file type 

Returns the file type of the specified file. 

ILLEGALFILE — 

Displays the error message "Illegal File*" and aborts the current task. 

INCLUDE" 

Used in the form: 

INCLUDE" <filename>" 
to include the contents of the blocks file "<file name>" by loading the first 
block in the file. 

INTERNAL -- n 

Constant value specifying the internal drive. 

lO-RESULT -- addr 

Returns the address of the variable containing the I/O result code of a file 
operation. 
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LOCK.FILE file* ~ 

Locks the file number specified. 

OPEN file^-- 

Opens the specified file. 

OPEN.RSRC file* ~ 

Opens the specified resource file. 

POINT pos mode\position\file* ~ 

Positions the file pointer to the specified location in the specified file. 

POSITION.FIXED rec^Xfile* - rec lenXfile* 

Fixed record file primitive. Positions the file pointer at the start of the 
specified record within the specified file. 

READ.FIXED addr\rec*\flle* — 

Reads the data from the file with number file* at the record with number 
rec* to addr. 

READ.TEXT addr\cnt\file* — 

Reads the data record from the file with file number file* at the current 
position to addr for a maximum of cnt bytes. If the record is larger than 
cnt bytes, the pointer in the file is left pointing at the last byte 
transferred. The next read (without adjusting the pointer) will begin with 
the rest of the record. 

READ.VIRTUAL addr\cnt\file addrXfile* — 

Reads the data from the file with file number file*, starting at the file 
address given to addr for cnt bytes. 

REWIND file* -- 

"Rewinds" the file pointer to point at the beginning of the file. 

REMOVE file*-- 

Removes the specified file number. 

SELECT file*-- 

Specifies the file number as the current blocks file. 

SET.EOF *bytes\file*- 

Sets the size of the file number given to the number of bytes specified. 

SET.FILE.INFO file*-- 

Writes the file information from the file's FCB to disk. 
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SET.REC.LEN rec lenXfile* -- 

Sets the fixed record length for the fixed record file specified. 

UNLOCKJiLE file* - 
Unlocks the specified file. 

USE" 

Assigns, opens, and selects the named blocks file. Used in the form: 
USE" <file name>" 

VIRTUAL — pos mode 

Returns the value which specifies that the file access is virtual. 

WRITE.FiXED addr\rec*\file* - 

Writes the data at addr to the record at rec* in the file with number file*. 

WRITE.TEXT addr\cnt\file* -- 

Writes the data at addr for cnt bytes (the last byte must be a carriage 
return) into the file with number file* at the current file position. 

WRITE.VIRTUAL addr\cnt\file addrXfile* - 

Writes the data at addr for cnt bytes into the file with number file* 
starting at the file addr given. 
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Chapter 10: Printer/Serial 



Topic Pag e 

Overview 2 

Text Output 2 

Window/Screen Output 3 

Other Printers 3 

Interfacing to Another Printer 4 

Printer Port Configurations 4 

Graphics Output 4 

Serial Interface 5 
Serial Communications with a Host Computer 5 

Serial Interface Implementation Details 6 



Printer/Serial Chapter 10-1 June 4, 1984 



Overview 

MacFORTH allows you to output anything that you can put on the screen, both 
characters and graphics, to an Apple Imagewriter printer. If you have any 
other type of printer, refer to a section at the end of this chapter entitled 
"Other Printers". 

Text Output 

Any character output to the screen can also be output to the printer. To do 
this, use one of three methods: 

a.) Select the "Printer" item from the "Options" menu. Output is then 
directed to both the printer and the screen. 

b.) Hold down the command key and press the key labelled 'P'. This 

selects the Printer menu entry, 
c.) Execute PRINTER OH to activate the printer. 

To disable output to the printer, you can use A or B above (they actually 
toggle the printer function ) or execute 
PRINTER OFF 

if you are doing any special formatting on the printer and don't want the 
output to appear on the screen, execute: 
PRINTER.OHLV CONSOLE ! 

To return output to both the printer and the screen, execute: 
llflC.CON CONSOLE ! 

PRINTER.ONLY does what its name implies. In the event of an error or if the 
end of the input is reached MacFORTH always returns to the console as the 



You can also direct any string to the printer with the word PRINT. PRINT 
works just like TYPE, only the string is output to the printer instead of the 
display. 

Many printers need a termination character (like CR or IF) before they will 
print the data sent to them. To output a carriage return or line feed execute 

CRLF 2 PRINT ( CR,LF) 

CRLF 1 PRINT ( just CR) 
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Window/Screen Output 

MacFORTH allows you to dump the contents of either only the active window 
or the entire screen to an Imagewriter printer. There are two methods of 
dumping the entire screen: 

A) Release the caps lock l<ey and then simultaneously press the 3 
keys labelled command shift 4 

B) Execute PR I NT. SCREEN 

To dump only the contents of the front window use one of the following two 
methods: 

A) Depress the caps lock key and then simultaneously depress 
command shift 4. 

B) ExecutePRINT.UINDOU 

It is also possible to print just a portion of the current window with the 
word PRINT.BITS. Used in the form 

<top> <left> <bottom> <right> <bitmap addr> PRINT.BITS 

the rectangle specified by <top> <left> and <bottom> <right> in the active 
window will be printed. The bitmap for a window is offset 2 bytes into the 
window record, so the address for the bitmap is GET.WINDOW 2+ 

For example, to print the contents of the upper left corner of the window, 
execute: 

50 60 GET.UINDOU 2+ PRINT.BITS 



Other Printers 

For best results, CSI strongly suggests the purchase of an Apple Imagewriter 
printer. If you choose to use another type of printer, you will have to either 
provide your own cabling and printer configuration or arrange with someone 
who can. 

Note: CSI does not guarantee that the instructions provided will enable you to 
interface to any printer other than the Imagewriter. The following 
information is intended to provide background information to individuals who 
have fabricated cables for and interfaced printers to other computers. It is 
not something that be attempted by inexperienced users. Beyond supplying 
background information, CSI will not support non-lmagewriter printers. 
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Interfacing to Another Printer 

In order to interface your non-lmagewriter printer to the Macintosh, you will 

need the following: 

a) a printer with an R5232C Serial interface, and 

b) a specially fabricated cable to connect between the printer and 
the Mac (refer to ST.MAC Magazine, 1984, pg.44 for Mac pinouts) 

c) be sure to satisfy the control signal requirements of your printer 
(ie. DSR, CD, RTS) 



Printer Port Configurations 

Default text output to the printer port occurs at 9500 baud, no parity, 8 data 
bits, 1 stop bit. Handshake protocol for output flow control is XON/XOFF. If 
your printer cannot be configured to this format, you will need to reconfigure 
the Mac printer port to a format your printer is capable of. Use: 

<«3top bit3> <parity> <«bil3> <baud rate> CONFIGURE. PR INTER 

where 



*stop bits 


1,2 = 


1 stop bit, 2 stop bits 


parity 


0,1,2,3 = 


none,odd,none,even 


*bits 


5,6,7,8 = 


* of data bits 


baud rate 


75-57600 





For example: 

1 8 1200 CONFIGURE. PR INTER 

reconfigures the printer port for 1 stop bit, no parity, 8 data bits, 1200 baud. 



Graphics Output 

Unfortunately, the Industry has no real standards for dumping graphics to a 

printer. In order to output graphics data to your printer, you will need the 

following: 

a) The ability to output text as described above (consider a printer buffer 

if necessary ). 

b) A complete understanding of the way In which your printer accepts 
graphics information. 

c) You will then have to write a program which determines which bits 
are set in the desired display area, format them into a output buffer 
which will be compatible with your printer, and then dump successive 
output buffers to the printer. Use the MacFORTH graphics word: 

GET.PIXEL (x\y - flag) 

to determine the state of each dot on the screen. 
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Serial Interface 

Screens 15 through 19 of the "FORTH Blocks" file on the MacFORTH system 
disc contain source code for the Macintosh serial communications port (the 
phone icon). To add the serial interface routines to your dictionary, load 
block 15 of the "FORTH Blocks" file. We have provided this source code for 
three reasons; 

First, it is optionally loadable. If you don't want to use it, you aren't 
penalized in memory usage. 

Second, many users of MacFORTH are newcomers to FORTH. This provides 
another example of FORTH source code. We encourage you to follow our 
example of spreading your applications source code over many blocks, leaving 
plenty of "white space" in your blocks. Note that each word is commented 
with both what is expected on the stack and a brief description of the action 
it takes. Many novice FORTH programmers try to cram as much as possible 
into a single block of source code, making it unreadable. Disks are cheap 
compared to the headache of trying to unravel an overstuffed block!! 

Third, for those users who have "Inside Macintosh", this is a good example of 
how to interface to a device driver entirely in high level FORTH. 



Serial Communications with a Host Computer 

The word HOST provides a simple terminal emulator. Set up the appropriate 
baud rate that your host computer expects with the word BAUD. For example, 
if your host communicates with you at 300 baud, you would execute: 
300 BRUD 

To enter into terminal emulator mode, execute: 
HOST 

To exit from terminal emulator mode, press the ~ key (it is the shifted key in 
the upper left corner of the keyboard). 
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Serial Interface Implementation Details 

Given the source code for the serial interface driver, you should be able to 
follow our path of logic. The following summarizes the contents of each 
block containing source code: 

Block 15: Serial Interface Load Block 

SERIAL.FILE* - addr 

Variable containing the file number to use for serial I/O operations. 
Actually, two files are required to support full duplex operations. 

SERIAL.IN --file* 

Returns the file number for the input side of the serial interface. 

SERIAL.OUT -file* 

Returns the file number for the output side of the serial inteface. 

INPUT.SIZE -size 

Constant containing the size of the serial input type ahead buffer. 
Change it to suit your requirements. 

INPUT.BUFFER —addr 

Returns the address of the input buffer. 

SERIALOPTIONS -addr 

Returns the addres of the array used to configure the serial 

interface protocol. 

Offset (bytes) Description 

XON/XOFF handshake enabled if byte is non-zero 

1 CTS handshake enabled if byte is non-zero 

2 XON character for software handshake 

3 XOFF character for software handshake 

4 Input abort codes: 

bit 4 = parity error 
bit 5 = overrun error 
bit 6 = framing error 

5 Status change generates event 

bit 7 = BREAK state change 
bit 5 = CTS state change 

6 Enable XON/XOFF input flow control if byte is 
non-zero 
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OPEN.SERIAL addrXcntXfile* — 

Opens serial device driver on the specified file*. (Note: 7FILES 
will show the serial files as ".AIN" and ".AOUT".) addr and cnt 
specify the address and length of the input buffer to be used for 
type ahead. This buffer is used to make up for the time it takes to 
scroll up all bits within the window. The options array is used to 
define the port protocol. 



Block 16: Serial I/O 

S.TYPE addrXcnt — 

Analagous to TYPE or PRINT. Output is sent to the serial port. 

S.EXPECT addrXcnt ~ 

Analagous to EXPECT. No character editing (eg. backspace) is 
performed. 

S.7TERMINAL -n 

Returns n as the number of characters available in the input buffer. 
Returns if none are available. 

S.STATUS ~stat2\stat1 

Returns the serial device status. 
Stat I : 

bit 30 framing error 

bit 29 hard overrun 

bit 28 parity error 

bit 24 soft overrun (input buffer overflow) 

bits 16-23 non-zero: XOFF received to stop input data 

bits 8- 1 5 read command pending 

bits 0-7 write command pending 

Stat 2: 

byte non-zero XOFF flag 
byte 1 non-zero CTS flag 



S.7READY —flag 

Returns a true flag if the serial driver is able to output (not held off 
by CTS or XOFF). 
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Block 17: Serial i/0 

S-KEY -- char 

Reads char from the serial port. If no characters are available, 
S.KEY waits until one is sent. 

S.EMIT char - 

Writes char to the serial port. Waits if not ready until ready for 
output. 

S.BREAK flag — 

Sets Break if flag is non-zero, otherwise clears break. 



Block 18: Serial I/O 

BAUD baud rate — 

Opens the serial port if necessary and sets the baud rate. 

Block 19: Serial I/O 

HOST 

Enters terminal emulation mode. Bi-directional XON/XOFF protocol 
supported. Exit via ~ key (shifted upper left key on the keyboard). 
Reducing the window size allows for faster throughput. 



Notes: 

(1 ) Input is not placed in the desk scrap. If you want to record transactions 
or transfer files, use HOST to logon and enter the editor. Exit and 
transfer data under program control. 

(2) You can change your textsize to allow either wider or narrower displays. 
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Chapter 1 1 : Advanced Topics 



In this chapter we will discuss a variety of liacFORTH features which you 
will find useful in the course of programming. 

Topic Page 

Time and Date Functions 2 

Timer Functions 3 

TRACE and DEBUG Features 3 

INTERRUPT Option 3 

DEBUG Option 3 

TRACE Option 4 

UNIQUE.MS6 Option 5 

LOWER.CASE Option 5 

QUIET Option 6 

User Specified Error Handlers 6 

Error Recovery 6 

Disabling Error Recovery 7 

Nesting Error Handlers 8 

Fixed Error Recovery 8 

Recovery Stack Frame Chart 9 

Memory Allocation 10 
Macintosh/MacFORTH Memory Map 1 1 

Vocabulary Data Structure 1 2 

MacFORTH Vocabulary Structure 14 

Character Cursor Symbol 1 5 
Cutting and Pasting Between 

Applications 16 

Macintosh Toolbox Interface 17 

Pre-Requisites 17 

Review of Pascal Data Types 17 

Toolbox Traps 17 

OS Traps 1 7 

Pascal Procedures 18 

Pascal Functions 18 

Complex Sound Generation 1 9 
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Time and Date Functions 

Your Macintosh maintains a count of the number of seconds that have passed 
since January 1, 1904 in its own internal counter. This counter is updated 
every second automatically by the computer and can be read by executing the 
word ©CLOCK. To facilitate using this feature, we have provided you with 
the following words to display the time and date: 

.TIMES — 

Displays the current time (as read from the internal clock) and 
displays it in the following format: 

HH:MM:SS XM 
DATES — 
Displays the current date (as read from the internal clock) and 
displays it in the following format: 

MM/DD/YY 

GET.TIMEI addr-- 

Copies the 1 1 byte time field ("HH:MM:SS XM") to addr. Be sure 
that you have 11 available bytes at addr as it will be 
overwritten. 

GET.DATES addr -- 

Copies the 8 byte date field ("MM/DD/YY") to addr. Be sure that 
you have 8 available bytes at addr as it will be overwritten. 

For more information on using the internal clock for display of time and date, 
refer to the MacFORTH Glossary entries for: 

FflT.DflTES FflT.rmES DflVS> 7SEC0NDS ?DflVS 



Timer Functions 

You can also use the clock as a timer. For example, to see how long it takes 
to display the entire words list of the current dictionaf7, you could execute: 
eCLOCK UORDS ©CLOCK SUflP - CR . ." Seconds" 

or to wait a specified number of seconds before continuing: 

I UflIT ( « of seconds -- ) 
eCLOCK + 
BEGIN ©CLOCK OUER - UNTIL DROP j 

30 URIT 
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TRACE and DEBUG Features: 

To facilitate debugging your program (if it has any bugs), we have provided 
you with an extensive set of tools for tracing and locating the problem. 



Interrupt Button Support 

When the user presses the interrupt button (the second button on the 
programmers buttons on the left side of the Mac) while MacFORTH is in 
control, MacFORTH locks out interrupts for a few seconds and then aborts the 
current operation. This action will recover from most unterminated loops and 
return control to the MacFORTH window. For example, try a definition like: 

: ENDLESS BEGIN ." again and again..." flGflIN j 

ENDLESS 

Now reach around and press the interrupt button ( not the reset button). 



DEBUG Option 

The debug option is present on the options menu bar. A check mark indicates 

the debug option is active. The keyboard equivalent command is command D. 

When the debug option is on, the text interpreter will check the stack depth 
after completion of each request. If any items are left on the stack, they are 
displayed using .5 in the following format 

[depth] \ 3rd stack item \ 2nd stack item \ top stack item 



The 3rd and 2nd stack items are only displayed if they exist. Refer to the 
trace option for other features of the debug option. 



Advanced Topics Page 11-3 June 4, 1984 



TRACE Option 

The trace option provides a compile time elective trace feature. Basically 
this option instructs the compiler to compile new definitions in such a way 
that when they are executed, the name of each word will be printed along 
with the depth and contents of the stacl<. The trace option may be set and 
cleared via the options menu bar. Pull down TRACE to toggle this function. 

For example, execute 
DEBUG ON 
TRACE OH 

: TEST 10 DO ." « " I . LOOP ; 

TEST 

Because the definition was compiled with the trace option on, when it 
executes, each word that is executed is preceded by printing its name and 
followed by printing the contents of the stack. (You can use the Menu Bar to 
halt and resume output.) 

The debug option enables and disables the run-time trace option's output. 
Now execute 

DEBUG OFF 

TEST 

and you will see that the trace feature was not executed because the debug 
option was off. 

NOTE: The trace option forces compilation of the trace feature into each word 
when it is turned on. The trace output is generated at run-time. This means 
that a great deal of overhead is carried with each word when it is executed 
with the trace option on. To get accurate timing information in time-critical 
operations, and for production applications code, disable the trace feature and 
re-compile the code. 

Remember, the TRACE option is altered by command D, You can toggle the 
trace function on and off during output by pressing command D (or by 
selecting the Debug item from the Options menu). 
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UNIQUE.MSG Option 

The text interpreter searches the current words in the dictionary when a new 
definition is created. If a new entry with a name field the same as a prior 
entry is created, the interpreter can optionally display the error message 

ISH'T UNIQUE 
The phrase 

UNIQUE.nSG OH 

enables output of this warning message when a word is re-defined (or given 
the same name as a prior word). The phrase 
UHlQUE.flSG OFF 

disables output of this message. For example, execute the following 
UNIQUE.nSG ON 
! TEST ; 
: TEST j 

UNIQUE.nSG OFF 
; TEST ; 

You normally want to operate with the UNIQUE.MSG option enabled, however, 
when loading production code with known re-definitions, you may choose to 
disable this message. 



LOWER.CASE Potion 

If you enter MacFORTH words in lower case, the text interpreter normally 
converts them to upper case before looking them up or creating a new 
dictionary entry. This allows you to reference a word by typing its name in 
upper or lower case. The phrase 
LOUER.CflSE OH 

defeats this automatic conversion and allows you to define MacFORTH words 
in lower case that have different name fields than their upper case 
equivalents. The phrase 
LOUER.CflSE OFF 

causes words to be again converted to upper case. The default state of this 
switch (at startup) is OFF. 
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QUIET Option 

MacFORTH normally sounds the beeper to attract your attention to an error. In 
some environments, this noise may be inappropriate. To quiet the beeper on 
errors, enter 

QUIET ON 

to sound the beeper on errors, enter 
QUIET OFF 

Default setting for this switch is OFF at startup. 



User Specified Error hiandlers 

MacFORTH allows you to dynamically install and remove handlers which 
intercept errors defined by ABORT" or ERROR" . Error handler entry points, 
specified by TRY and ON.ERROR , are dynamically installed and remain active 
for the current definitions. If an ABORT" occurs or a RECOVER attempt is 
made within that def intion or any definition which it executes, the specified 
error handler will be invoked (unless another handler has been invoked at a 
lower level). When the current definition completes, error handling specific 
to that definition is replaced by that of the next higher level. Thus, error 
recovery is fully nested, and the scope of any error handler specified within 
a definition is relevant only to that definition (or those it references). For 
example, 

: OOPS! U/nOD j 

OOPS! 

invokes a division by zero processor exception handler to execute the 
following: 

ABORT" ZERO DIUIDE TRAP ! " 



Error Recovery 

Because no exception handler was specified, the default abort occurred. By 

using ON.ERROR to specify a new handler, you can override the default 

message; 

: TEST ( - ) 

ON.ERROR ." TEST RBORTED " RBORT RESUHE 
." TEST STRRTED " OOPS! 
." TEST COHPLETED " ; 

TEST 
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What TEST did was to create an error handler to process the abort condition. 
The phrase 

ON. ERROR ." TEST RBORTED " ABORT RESUflE 

defined the error handler to display the message "TEST ABORTED" and then 
execute ABORT when an ABORT condition occurred. 

Disabling Error Recovery 

You may cancel a posted retry handler at any point with the phrase 
RETRY OFF 

For example: 

! TEST4 ( — ) 

OH. ABORT ." TEST4 RBORT ROUTINE" RETRV OFF RESUriE 
CR ." INLINE TEST4 " CR OOPS! ; 

TEST4 

Let's follow what happened when you executed TEST4 ; 

ON. ERROR ." TEST4 RBORT ROUTINE" RETRV OFF RESUNE 

set up the new error handler. 

CR ." INLINE TEST4" 

displayed the message, 
CR OOPS! 

caused an abort condition to occur. From here control was passed to the error 
handler, which displayed the message "TEST4 ABORT ROUTINE" and set RETRY 
to zero. Control was then passed to the code following THEN in TEST4, which 
again executed 

CR ." INLINE TEST4" CR OOPS! 

This time, with RETRY set to zero, the default error handler was executed and 
the system aborted with the message "ZERO DIVIDE TRAP !" 

Setting RETRY to zero only affects the most recently defined error handler 
(which is automatically removed at the end of the current definition anyway). 
Any previously defined error handler will be re-installed when the current 
definition is completed, allowing nesting of error handling routines. 
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Nesting Error Handlers 

For nested RETRYs, you may want to include the following definition: 

: PRIOR.RETRV ( — I pops the recovery stack frame ) 
( off of the return stack ) 

RETRV e ?DUP IF 12 + e RETRV ! THEN ; 

This definition will remove the recovery stack frame off of the return stack 
and point RETRY at the next frame in the list (the list is zero-terminated). 
: TEST6 ( — ) 

OH. ERROR ." FIRST ABORT" PRIOR.RETRV 

ELSE ON. ABORT ." SECOND ABORT" PRIOR.RETRV 

RESUI1E 
RESUHE OOPS! ; 

TEST6 

This example has shown multiple-level nesting of the error handlers using 
RETRY . The first level error handler will display the message "FIRST ABORT" 
and reset the error handler to the next higher handler (in this case, the 
default handler). The second level error handler will display the message 
"SECOND ABORT" and reset the error handler to the next higher handler (the 
first level error handler). 



Fixed Error Recovery 

: TEST? ( f ~ ) 

ON. ERROR PRIOR.RETRV 1 ABORT" TEST? ABORT ROUTINE" 
RESUI1E 
IF RECOUER ELSE 60 SVSBEEP THEN ; 

TEST? 

1 TEST? 

displays the message "TEST? ABORT ROUTINE." RECOVER unconditionally 
recovers at the most recently specified recovery stack frame. 
: TEST8 ." VV" RECOUER j 

TEST8 

The error message "ILLEGAL RECOVERY ATTEMPTED" indicates that an 
attempted was made to recover with no handler posted. 



Advanced Topics Page 11-8 June 4, 1 984 



: TEST9 ( — ) 

2 TRV 1- ." KX" DUP 
IF TEST8 THEH 

." ZZ" ; 
TEST9 

ON.ERROR posts a handler and jumps over it, TRY posts a handler and continues 
to execute, In either case the stack pointer is returned to the depth that it 
was when the error handler was identified. This technique is most often used 
to identify the last ditch error handler in a fault tolerant system. TRY may be 
used to restart the current program function in case of an unexpected error 
condition. 



// 



RP-> 



Prior Retry 



Recouery SP 



Recovery IP 



// 



Address of NO.RETRV 



// 



// 



<— 



Recovery Stack Fraae 



User Uariable 
RETRV 



This stack frame approach allows you to specify your own ABORT" error 
handler at any level without disrupting a handler posted at a higher level. 
When the current definition completes, the posted handler is automatically 
replaced by the immediately higher level (if present). 

The list of stack frames is terminated by zero which, when RETRY points to it 
(the zero entry), indicates that the default error handler is to be used. 
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Memory Allocation 

Macintosh memory is partitioned into the five major areas shown in the 
Macintosh and MacFORTH Memory Maps that follow. The areas titled 
"Application Heap" and the stack are all that you need concern yourself with. 
The remaining areas support system functions normally outside the scope of 
applications programs. The applications heap area is a chunk of memory under 
the control of the toolbox memory manager. 

When writing MacFORTH programs, you control the amount of memory 
allocated to your current object and vocabulary data structures. When 
MacFORTH is loaded into memory from disc, it is placed by the toolbox 
memory manager at the base of the applications heap. The applications heap 
is just a pool of memory from which programs can request variable length 
chunks. 

The memory manager will attempt to satisfy your request by looking at all of 
the available pieces in the heap and if a big enough piece isn't available, it 
will reshuffle the heap until it can put together enough smaller chunks to 
satisfy your request. You can also ask the memory manager to increase or 
decrease the size of an existing chunk of memory. 

After it is loaded, and the desktop window is initialized, MacFORTH asks the 
memory manager to allocate a chunk of memory to put programs and data in. 
Because the object area will contain executable code, it must be locked down 
in memory, while its size may still grow and shrink. 

A default allocation of 8K of object space and 9.5K of FORTH vocabulary space 
is made. 

MacFORTH Level 2 provides an indepth discussion of heap collection and 
allows you to allocate your own relocatable heap data structures. 



Advanced Topics Page 11-10 June 4, 1984 



Macintosh 
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Heap 



System 
Heap 



Globals 
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MacFORTH 
Memory Map 



Block Buffers 



TIB \ Return Stack 



STACK 
(grows down) 



HEAP 
(grows up) 



Other Vocabularies 



Resizable 
MacFORTH Vocabulary 



Resizable 
MacFORTH Object 



Desktop Window 



MacFORTH 

Precompiled 

Object 



User Area 
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Vocabulary Data Structure 

MacFORTH supports vocabularies as a linked list of words located in a data 
structure allocated from the heap. (Refer to vocabulary Structure Diagram.) 

When a word is defined in MacFORTH, the "head" of the definition, including 
the text for the name, and it's associated token is placed in the current 
vocabulary, and the "body", including associated data or execution structures, 
is placead in the object Image. 

A number of MacFORTH operators exist for manipulating the vocabulary and 
object area data structures. 



N VOCABULARY TEST 

Creates a new vocabulary called TEST, The Initial allocation of space 
for TEST will be N bytes. 

APPEND (tokenXstr.addr ~ ) 

Appends the supplied token and string to the current vocabulary. 

TEST 

Sets TEST as the context vocabulary. 

TEST DEFINITIONS 

Sets TEST to the current vocabulary. 

N RESiZE.VOCAB 

Attempts to RESIZE the current vocabulary to N bytes. Error 
messages are reported if insufficient heap space is available or if N 
is too small to contain vocabulary. 

-LATEST 

Purges the latest vocabulary entry, returning space to the vocabulary. 

N BEHEAD 

Purges the name head for the token represented by 'H' from the 
vocabulary. 

AXE NAME 

BEHEADS the vocabulary entry for 'NAME'. 
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FIND ( ~ token or ) 

Returns the applicable token value for the next word In the input 
stream. For example: 

FIND DUP 
returns the token for DUP . 

NFA (token ~ name addr ) 

Returns the address for the name of the vocabulary entry that 
corresponds with the supplied token. For example: 

FIND DUP NFA ID. 
will obtain the token DUP , convert it to it's Name Field Address, and 
then type out the Name. 
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MacFORTH 
Vocabulary Structure 
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die 
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u 



Zero Token indicates 
end of Vocabulary List 



First Name in Vocabulary 
"EXIT" 



Token for First Name in 
Vocabulary 

Names and Tokens Between 
First and Latest 



Latest Name In Vocabulary 

Token for Latest Name 
"NEW" 

Available Space in Vocabulary 
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Current Vocabulary Size 
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Character Cursor Symbol 

When MacFORTH is waiting for text from the keyboard, a flashing cursor is 
displayed at the point where the text will be placed. The flash rate is set via 
the control panel. 

Any character font may be used as the cursor. The variable CURSOR.CHAR 
contains the font* in the first 16 bits and the character in the second 16 bits. 
For example: 

HEX 5F CURSOR.CHAR ! DECiriRL 

sets the cursor to the default underline cursor. 
BL CURSOR. CHRR ! 

sets the cursor to blank (invisible) 

HEX 7C CURSOR. CHRR ! DECiriflL 

sets the cursor to a vertical bar (as in MacWrite) and 
HEX 070041 CURSOR. CHRR ! DECiriRL 

sets the cursor to character 41 (A) of font*7. 

Changing the cursor symbol is a good way of alerting the user when the 
system is in some special mode. Some of the different character cursors we 
have experimented with are listed below: 



Hex Value 


Symbol 


11 


hollow apple 


12 


checkmark 


13 


diamond 


14 


dot 


15 


solid apple 


C6 


triangle 


BO 


infinity symbol 


BD 


omega 
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Cutting and Pasting Between Applications 

One of the more innovative features of the Macintosh is its ability to cut and 
paste between applications. This is done utilizing a facility known as the 
Desk Scrap. The Desk Scrap is maintained by the Toolbox Desk Manager. 
MacFORTH currently supports two types of scrap entries: TEXT and PICT. 

MacFORTH Level I supports cutting and pasting of text data between the text 
editor and the desk accessories, or other applications. This is built in to the 
editor and explained in the Program Editing chapter. Unless you need to 
handle text larger than fits on a block of source code, you don't need to 
concern yourself with the desk scrap. 

Accessing the Scrap 

The following words are available for accessing the desk scrap (refer to their 

definitions in the glossary for more information on each): 

SCRAP . LEN SCRAP . HANDLE SCRAP . COUNTER 

ZEAO. SCARP GET. SCRAP PUT.SCRRP 

UNLOAD. SCRRP LORD. SCRAP "TEXT 

"PICT 

The text editor source code is a good example of accessing the desk scrap. 
Refer to the source code in the "Editor Blocks" file. 
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Macintosh Toolbox Interface 

This section documents the facilities to directly call routines in the 
Macintosh toolbox from high level MacFORTH. 

Pre-reauisites 

The objective of this section is neither to document the contents of the 
Macintosh toolbox, nor explain the interworkings of Mac/Lisa Pascal. To gain 
insight into those areas you need to obtain a copy of "Inside Macintosh." 

As a minimum, you will need to read and understand the "Programming 
Macintosh Applications in Assembly Language" section of the manual. Add to 
this any parts of the toolbox that you want to access. 

Review of Pascal Data Types 

The following data types are used throughout: 

Boolean: 15-bit word with LS bit set in the high order byte to 

indicate true or false (true = 1 ) 



Byte: 


16-bit word wi 


Char. 


same as Byte 


Integer: 


16-bit word 


Long Integer: 


32-bit word 


Pointer: 


32-bit address 


Handle: 


32-bit pointer 




pointer 


Toolbox Traps 





to an address which contains a 32-bit 



Macintosh toolbox traps occur in 3 areas: 

OS Traps: All OS traps uniformly expect an I/O buffer pointer in AO and 
return an I/O result in DO. The MacFORTH defining word OS.TRAP creates a 
new word, which when later executed, pops the top item of the stack into AO, 
executes the trap, saves the result in the user variable lO-RESULT, and then 
executes NEXT. OS traps are defined in the following form: 

HEK 

fl002 OS.TRfiP READ ( buf ptr ~ ) 

fl102 OS.TRfiP flSVHC.RERD ( buf plr -- ) 

DECmRL 

and may be used in the form: 

1 >FCB READ 7FILE.ERR0R 

(Refer to the File System chapter for details on each command.) 
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Pascal Procedures: Pascal procedures are a little more complicated. There 
may be more than one argument passed and they may be of jumbled data types 
(15-bit values, including booleans, bytes, or words intermixed with 32-bit 
values). Fortunately, the majority of toolbox procedures either expect all 
32-bit items or only the last one or two items are 16-bit values. 

Uniform 32-Bit Procedure Calls : Because MacFORTH works with 32-bit stack 
data, Pascal procedures which expect 32-bit arguments may be easily defined 
with MT. For example: 

HEX fl915 ni HIDE.UINDOU ( wptp ~ ) DECiriflL 

When HIDE.WINDOW is executed, the trap A915 (hex) is executed with wptr 
on the stack. 

Note: When passing parameters to Pascal procedures, just leave them on the 
stack in the order described in the Apple documentation (left is deepest stack 
item). 

Procedure Call with 1 16-bit Item on the Tod of the Stack: Enough of these 
exist to warrant a special operator.: 

HEX fl9C8 U>nT SVSBEEP ( duration ) DECiriRL 

This operator works for all cases in which all arguments below the top of the 
stack (if any) are 32-bits. 

Procedure Call with 2 16-bit Items on the Tod of the Stack: Enough of these 
exist to warrant a special operator: 

HEX fl893 2U>nT (LI HE. TO) ( x\y - ) DECinflL 

Note: The trap values shown differ from those in the Apple documentation (ie. 
ADC8 for SysBeep, AC93 for LineTo, etc.). The 11 th bit set in the Apple 
documentaion is an artifact of a prior generation Pascal compiler. Don't ask 
why, just use the correct lower value. It's what the new compiler uses. 

Pascal Functions: Unfortunately, Pascal functions expect space reserved to 
return the result under any passed arguments. This means we have to pop off 
all of our arguments, push space into the stack for the returned result, and 
the push back the arguments. This is further complicated by the fact that the 
result may be either 16 or 32-bits in length. As you may have guessed, some 
of your favorite toolbox traps (like NEW.WINDOW which takes 9 parameters!!) 
are function calls. 

MacFORTH provides toolbox trap defining words for the easy function calls. 
The harder ones you'll either have to include a zero in your argument list (to 
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reserve space for the result), or write in with the Level 2 MacFORTH 68000 

assembler. The following function traps are supported: 
FUNOW returns a 16-bit result 

(ie: fl861 FUHOU RflHDOn ) 
FUNOL returns a 32-bit result 

W>FUNC>L word parameter, long result 

L>FUNC>L long parameter, long result 



Complex Sound Generation 

MacFORTH provides access to the Macintosh OS sound driver. The sound driver 
provides three different sound synthesizers: 

- square wave synthesizer: produces a pre-programmed series of tones 

- four tone synthesizer: produces simple harmonic tones (with up to 4 
voices) 

- free form synthesizer: produces complex music and speech 

When the system is loaded, MacFORTH opens the device driver ".SOUND" and 
assigns it to its own FCB called SOUND.FCB. The Getting Started chapter 
discusses how to generate simple tones via the sound driver. For more 
complex sounds, you will need to create your own waveform record. For 
instructions on how to construct any desired free form or four-tone 
synthesizer record, refer to the in-depth discussion on sound generation In 
the Apple documentation. 

A MacFORTH sound record consists of a synthesizer record proceded by a 
16-bit word containing the length of the following synthesizer record. Two 
operators are available to play your synthesizer record: 

PLAY sound record address — 
Plays the desired synthesizer record, hangs the cpu until It finishes. 

APLAY sound record address — 
Asynchronously plays the desired synthesizer record. The processor 
continues execution and the sound Is generated concurrently. 

Refer to the sourc code of the demos for examples of how to define you own 
music using the square wave synthesizer. 
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Chapter 12 : MacFORTH Error Handling 

This section discusses the method i^acFORTH uses to handle errors. The 
topics discussed in this section are: 

Topic Page 

Overview 2 

Compiler and Interpreter Errors 3 

File Errors and Processor Exceptions 4 

MacFORTH Default Error Message Summary 5 
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Overview 

By default, when MacFORTH encounters an error condition, an error message 
is displayed, the current operation is aborted, and control is returned to the 
system window. Error conditions occur in the following categories; 

Interpreter 

Compiler 

Utility 

File 

Processor 

You can override any default exception error handler. All of the messages in 
the preceding sections are listed in alphabetical order in the back of this 
section with accompanying text discussing the probable cause of the error 
and what action to tal<e. 

The errors supplied by the Macintosh that are specific to file handling are 
listed in Appendix B of the File System chapter. 
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Compiler and Interpreter Errors 

Compiler and Interpreter errors can be divided as follows: 
Interpreter Errors 

7 

BELOW FENCE I 

STACK EMPTY 

MISSING STRING DELIMITER 

DECLARE VOCABULARY 

MISSING IFEND OR OTHERWISE 

Compiler Errors 

? 

COMPILATION ONLY, USE IN A DEFINITION 

CONDITIONALS NOT PAIRED 

DEFINITION INCOMPLETE 

DICTIONARY FULL 

EXECUTION ONLY 

MISSING STRING DELIMITER 

ATTEMPTED TO REDEFINE NULL 

Because these errors are more pertinent to the program development 
process rather than run time applications, they are defined with the word 
ERROR" . An example of ERROR" is 

FENCE @ < ERROR" BELOW FENCE" 

If the value of the stack is non-zero, the console buzzer is sounded (if the 
QUIET option is ON), a carriage return is output followed by the most 
recently interpreted word and the errr • message. If the error occurs while 
interpreting text from disc, the serf in* and offset are placed in the user 
variables SCR and R* When you enter the editor the cursor will 
positioned Immediately after the error. 
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File Errors and Processor Exceptions 

File errors and processor exceptions are sub-divided as follows: 

File Errors 

MEDIA WRITE PROTECTED I 
DRIVE NOT READY I 
DISC SEEK ERROR! 
INTERRUPTED 

Processor Exceptions 

ADDRESS ERROR TRAP AT XXXXXX 
BUS ERROR TRAP AT XXXXXX 
ILLEGAL INSTRUCTION TRAP I 
OVERFLOW TRAP I 
ZERO DIVIDE TRAP! 

These errors are defined with the word ABORT" . An example of ABORT" is 

MAX.BLOCK > ABORT" ILLEGAL BLOCK ^ " 

If the value on the top of the stack is non-zero, and no user supplied 
recovery stack frame has been established (discussed in next section), the 
default error handler outputs the message text and executes ABORT to 
return control to the console. While the default handler works well in the 
normal program development process, you will often choose to supply your 
own error handlers to recover from device errors and processor exceptions 
in actual applications. 
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MacFORTH Default Error Message Summary 

When a system error is encountered, the MacFORTH system stops and outputs 
an error message. All system error messages and a discussion of their 
probable cause is provided below. 

File I/O errors are discussed separately in the File System 
chapter. 

Message Probable Cause 

? The text interpreter was unable to find <string> in the CONTEXT or 

TRUNK vocabularies and was unable to convert it to a number. 
Probably a typo or the word has not been loaded, 

ABORTED FROM KEYBOARD 

A keyboard abort event occurred. 

ADDRESS ERROR TRAP AT XXXXXXX 

An attempt was made to fetch or store a 16-bit or 32-blt value at 
odd address XXXXXXX, The 68000 hardware does not allow this. 
Either align the data structure on an even word boundary (using 
?ALIGN)oruseCMOVE. 

ATTEMPED TO REDEFINE NULL 

MacFORTH prevents the user from inadvertently redefining the end 
of line function (NULL) by typing : followed by a carriage return, 
as this would cause the system to respond to carriage returns in 
an unpredictable manner. If you truly wish to redefine the 
function of NULL , and understand fully the overall system impact, 
use the following: 

: X <your definition for nuli> ; 
HEX R020 TOtCEN.FOR X NFR U! 

BUS ERROR TRAP AT XXXXXXX 

An attempt was made to access data at address XXXXXXX which is 
invalid. Neither memory nor hardware is capable of responding at 
the address. 

CANNOT CLOSE SYSTEM WINDOW I 

While it is possible to hide the MacFORTH window, you cannot 
close it. 
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Message Probable Cause 

CANNOT LOAD BLOCK ! 

Block of each file is reserved for data or comments. You are 
unable to load it. Use a higher block number. 

COMPILATION ONLY USE IN A DEFINITION I 

The offending word was encountered in execution state. The word 
is a compiler primitive and has no meaning when not compiling (ie: 
DO IF LOOP BEGIN ) . 

CONDITIONALS NOT PAIRED 

The text interpreter expects all conditionals to be properly nested. 
A terminating conditional (THEN , UNTIL , REPEAT , AGAIN, 
LOOP , +LOOP ) was encountered for which there was not a 
corresponding acceptable initializing conditional (IF, ELSE, DO , 
BEGIN , WHILE ) at the correct nesting level. 

DEFINITION INCOMPLETE I 

The stack depth changed inside a colon definition. This is normally 
the result of an unpaired conditional (ie: a missing THEN). It may 
however, result from using a literal inside a definition to compile 
a literal value that was left on the stack prior to defining a word. 
In this case modify the user variable CSP to indicate the 
difference, ie: one item dropped from the stack requires 

[ 4 CSP +! ] 
Warning: Conditionals leave various information (address, 
conditional type) on the stack at run time. Be aware of this when 
placing literals inside colon definitions. 

DICTIONARY FULL ! 

Less than 260 (decimal) bytes exist In the object dictionary. If 
allowed to continue, scratch pad buffers above dictionary could 
overwrite the end of the object space. FORGET to free up 
dictionary space or resize the object area. 

EXECUTION ONLY ! 

The offending word may not occur while compiling. 

FILE ERROR* 

An unidentified file error occurred. Refer to the File System 
chapter for identified file errors. 
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Message Probable Cause 

FILE NOT OPEN ! 

An attempt was made to access a file that was not open. Open the 
file and continue. 

FIXED RECORD LENGTH = I 

FORTH blocks are merely fixed length records within a file. In 
order to access them, the record length for the file must be 1024 
You probably attempted to read a text file as blocks. 

ILLEGAL FILE NUMBER ! 

MacFORTH file numbers range between and 9, any other value is 
illegal. Check the order of your operands. 

ILLEGAL INSTRUCTION TRAP! 

The 68000 attempted to execute an invalid (unrecognizable) 
instruction probably due to accidentally overwriting the 
dictionary. Try to locate erroneous code which overwrites 
dictionary. 

ILLEGAL RECOVERY ATTEMPTED I 

An Attempt was made to recover from an error condition with no 
ON.ERROR recovery handler posted. 

ILLEGAL VOLUME I 

The MacFORTH DIR command expects either a drive name (internal 
or external) or a volume reference number to produce a directory. 

WARNING; Disc full at block * 

ADD.BLOCKS encountered an end of volume condition. No more 
space exists on the disk. All available space is allocated. 

ISN'T UNIQUE 

A word was created in the dictionary which is not unique in the 
CURRENT , CONTEXT , or TRUNK vocabularies and the UNIQUE.MSG 
switch is off. The most recent definition will be used for future 
references. The prior definition probably cannot be found. This 
warning message may be disabled when loading production code by: 
UNIQUE.MSG OFF 

MISSING ( STRING DELIMITER ! 

The input stream was exhausted (null encountered) before a 
delimiting right paren was found. See the MISSING STRING 
DELIMITER error message also. 
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Message Probable Cause 

MISSING [ STRING DELIMITER 

The input stream was exhausted (null encountered) before a 
delimiting right brace was found. See the MISSING STRING 
DELIMITER error message also. 

MISSING IFEND OR OTHERWISE 

MacFORTH does not allow IFTRUE ... OTHERWISE... IFEND... or 
IFTRUE...IFEND conditional compilation sequences to cross either 
input line or block boundaries. Reorganize your text to start and 
end such sequences on the same source block or input line. 

MISSING STRING DELIMITER 

The input stream was exhausted (null encountered) before the 
required delimiter was found. Delimited strings may not cross 
block or terminal input line boundaries. Insert trailing delimiter 
in source text. 

NO FCB'S AVAILABLE 

All FCB'S were in use when the NEXT.FCB command was executed. 

NOT A BLOCKS FILE! 

An attempt was made to select a non-blocks file as the current 
blocks file for editing. 

NOT ENOUGH STACK ITEMS I 

Insufficient stack items where placed on the stack before 
executing the most recently entered word. MacFORTH selectively 
contains a few operators which provide this check. In applications 
code use; 

X NEEDED 
Where X is the number of items required to properly execute. 

OBJECT DICTIONARY FULL I 

Object dictionary space is full. Use ROOM and RESIZE.OBJECT to 
allocate more object space from the heap. 

OBJECT WONT FIT! 

An attempt was made to resize the object dictionary into a 
memory segment which Is too small. 

OVERFLOW TRAP ! 

Default handler for exception caused by TRAPV instruction - see 
Motorola documentation. 
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Message Probable Cause 

RANGE TRAP ! 

User assembly code generated a range TRAP from a CHK, 
instruction. See MacFORTH Level 2 Assembler documentation. 

STACK EMPTY I 

Text interpreter found the stack pointer greater than the top of 
the stack . An attempt was made to access nonexistent stack data. 
NOTE: There is no run-time check made by the address interpreter. 
When executing code underflows the stack, the contents of the 
text input buffer and eventually the return stack are unpredictable. 
A buffer zone of 2 bytes is reserved for minor underflow 
occurrences. 

SOUND ERROR! 

The sound generation driver reported an error to MacFORTH. 

UNABLE TO RESIZE OBJECT! 

The memory manager was unable to increase the size of the object 
space due to the placement of a fixed/locked memory segment 
immediately behind it. Refer to the Advanced Topics chapter for a 
discussion of memory allocation and resizing. 

UNABLE TO RESIZE VOCABULARY ! 

The memory manager was unable to increase the size of the 
vocabulary space due to the placement of a fixed/ locked memory 
segment immediately behind it. Refer to the Advanced Topics 
chapter for a discussion of memory allocation and resizing. 

VOCABULARY FULL ! 

The current vocabulary is full. Use RESIZE. VOCAB to allocate more 
vocabulary space. ROOM displays current allocation. Refer to the 
Advanced Topics chapter for more information on memory 
allocation. 

VOCABULARY WONT FIT! 

An attempt was made to resize the vocabulary into a memory 
segment which is too small. 

ZERO DIVIDE TRAP i 

The 68000 attempted to divide by zero in hardware. 
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MacFORTH Glossary 

This section presents the MacFORTH glossary. It is divided into three 
parts: 

1) An index in sorted ASCII order with page number reference. 
Useful for finding a particular word quickly. 

2) An index by function with page number reference. Useful for 
finding a word in a particular class. 

3) The definitions themselves in sorted ASCII order. 

The authors have put an enormous amount of work into this glossary. 
Users who want to get the most out of MacFORTH should read through it at 
least once to get an idea of the wide range of capabilities that are 
available. 

Glossary Key 

The following symbols are used in the glossary to indicate the contents of 
the parameter stack before and after execution of the particular word: 



Symbol 



Meaning 

Prefix used to indicate a string field 
operation. By itself, it indicates a 
string address. As a prefix to cnt 
($cnt) it indicates a string field 
count. 



addr 



A memory address. A number suffix is 
used to differentiate between 
addresses. 



bool 



A boolean flag. A value of zero 
indicates a false flag; non-zero 
indicates true. MacFORTH words which 
return pure boolean results use - 1 as 
a true flag ( all bits set). 



char 



An 8-bit character value. 
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Symbol Meaning 
cnt 



A count value. Usually used with an 
addr symbol to designate the start- 
ing address and count for an array of 
string value. Also used to designate 
the width of a field. 



dest 



Refers to a destination address. 



false 



A boolean false flag (0). 



flag 



A special flag value. The specific 
meanings for different flag values are 
discussed in the text of the defin- 
itions for the word which uses the 
flag. 



norun 



A 32-bit integer. A number suffix is 
used to differentiate between num- 
bers. The prefix u indicates the 
number is unsigned. 



src 



Refers to a source address. 



true 



A boolean true flag(-l). 



w 



A 16-bit integer. A number suffix is 
used to differentiate between num- 
bers. 



wptr 



Starting address of a window table. 
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Symbol Meaning 

\ Delimits items on the stack. It is pro- 

nounced "under". For example, 

n 1 \n2 ~ addr 
Is read "nl under n2 leaves addr" . 

[...]or[...] Indicates different possible stack 

outcomes. For example, the word ?DUP 
duplicates the top item on the stack 
If it is non-zero. It's stack notation is 

n — [n\n] or [n] 
Indicating an Integer Is expected 
on the stack and leaving either two 
items ( n under n) or the original 
integer Itself. 

In some of the definitions, we have used a more mnemonic name for a 
parameter instead of a standard symbol for clarity. For example, "index" Is 
used to Indicate an Index value, "sect" is used to Indicate a sector on a 
disk, "blk*" refers to a block number, and so on. 

Always refer to the text of the definition for a more complete explanation 
of the required parameters. 

A Few Notes on the Glossary: 

Most FORTH glossaries are noted for their small size (typically less than 
250 items). The MacFORTH glossary contains about 900 entries. This Is 
due to the extensive access to the Macintosh toolbox provided by 
MacFORTH. Normally, the MacFORTH kernel Is about 250-300 words. 
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i nXaddr ~ 

Store n at addr. "store" 

The error message "ADDRESS ERROR TRAP AT addr" Indicates addr Is 
odd (addr Is displayed as a hexadecimal value) Refer to the Error 
Handling chapter for a further explanation. 

rcsp 

Save the current stack position In the User Variable CSP . This is used 
as part of the compiler security to ensure the stack does not change 
during compilation of a word, "store-c-s-p" 

IPENSTATE 20 bytes - 

Restores the prior penstate from the stack. See @PENSTATE . "store 
pen state" 

IPOINT x\y\addr -- 

Packs the 16-bit values x and y into a 32-bit integer and stores the 
value at addr. 

IRECT top\left\bottom\right\addr — 

Packs the rectangle coordinates on the stack into 4 l6-blt values and 
stores them at addr. Packed rectangle contains 4 16-b1t elements In 
top- left-bottom-right sequence, "store rect" 

!5R n - 

Directly stores the least significant 15 bits of n into the 68000 
hardware status register. The supervisor and trace modes, interrupt 
level, and condition codes are affected, "store-s-r" 

~ addr 
Compiles a string delimited by " , leaving its address when the word 
is later executed. Used during compilation in the form: " <string 
literal>" to compile ($LIT) followed by <string llteral> with its count 
in the first position. When later executed, {$LIT) places the address 
of <string llteral> on the stack, advancing the instruction pointer to 
the word following the string literal. See SLIT , ($LIT) , ." , ," "quote" 

-BLK5 - n 

32-bit constant containing the 4 character ASCII string "BLKS" . Used 
to designate the blocks file type, "quote B-L-K-S " 
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-DATA - n 

32-bit constant containing the A character ACSII string "DATA" . Used 
as a file or resource type, "quote DATA " 

-PICT - n 

32-bit constant containing the 4 character ASCII string "PICT". Used 
to designate a picture file or resource types, "quote P-l-C-T " 

-TEXT -n 

32-bit constant containing the 4 character ASCI I string "TEXT" . Used 
to designate text files or resource types, "quote TEXT " 

-M4TH - n 

Constant MacFORTH File creator id code. Placed in the creator field of 
all files created by MacFORTH. "qoute M-4th" 

* n1~n2 

Uses nl to generate the next ASCII character for numeric output, 
leaving n2 as nl/BASE. The result n2 Is maintained for further 
processing. Unchecked error if not used between <* and *> . See <* 
and *> . "sharp" 

*> n — addr\cnt 

End pictured numeric output conversion. Drop n from the stack and 
leave the address and count of the text string created during numeric 
conversion, "sharp-greater" 

*FILE5 ~ n 

Constant specif ing the maximum number of files that can be opened at 
once. 

*FIND - 1 \voc addr 1 \...\voc addr n ~ [token\len\true] or [false] 

Search the -1 terminated vocabulary list for the word in input 
stream. If the word is not found during the search, leave a false flag. 
If the word is found, leave its token, length byte and a true flag, voc 
addr is the handle of the vocabulary token "hash-find" 

*S un ~ 

Converts all digits of unsigned un. Each is added to the pictured 
numeric output string until the remainder is zero. A single zero is 
added to the output string if un was initially zero, "sharp-s" 
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SADDR - addr 

Skips over following In-line string literal, leaving address on stack, 
"string address" 

$LIT ~ addrXcnt 

Executes (SLIT) . Necessary to match nesting level (return stack 
depth) for other Inline string literal operators such as (ABORT") and 
(ERROR") which also use (SLIT) . See (SLIT) . "string-lit" 

~ pfa 
Used in the form: ' <name> to get the pfa of <name>. If executing, 
leave the pfa of the next word in the input stream. If compiling, 
compile this pfa as a literal; later execution will place it on the 
stack. Issue an error message if the word is not found after a search 
of the CONTEXT and then the CURRENT vocabularies. Within a colon 
definition ' <name> Is Identical to [ ' <name> ] LITERAL . Error 
if the following word is not found in the dictionary. The system will 
print the name followed by a question mark, "tick" 

■INTERPRET - 

Begin Interpretation of the Input stream pointed to by >IN and BLK . If 
BLK is non-zero, >IN points to the character within the block pointed 
to by BLK . If BLK is zero, the input stream is taken from the 
Terminal Input Buffer. See >IN , BLK , TIB . "tick-interpret" 



c 



Accepts and ignores comment characters from the input stream until 
the next right parenthesis. Used in the form; ( ccc ) or ( ccc) The 
left parenthesis must be followed by at least one space (as with all 
FORTH words). It may be used freely while compiling or executing. 
The error message MISSIN6( STRING DELIMITER I Indicates the input 
stream has been exhausted before the delimiting right parenthesis 
was encountered, "paren" 
The delimiter (right parenthesis) is pronounced: "close-paren" 



(ION.ACTIVATE) - 

Runtime word for lON.ACTIVATE . Use ION.ACTIVATE 

(ION.UPDATE) ~ 

Runtime word for iON.UPDATE . Use ION.UPDATE . 
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(SLIT) - addr 

Fetches the Inline string literal address from the return stack, 
leaving the string address on the stack. The value on the return stack 
(the Instruction pointer) Is Incremented to point just past the string, 
so when (SLIT) executes EXIT , execution will continue beyond the 
string literal, "paren-strlng-llt" 

((ABORT)) -- 

Default version of ABORT (initially placed in (ABORT) ). Empties the 
data stack, RELEASES the disk, sets BASE to DECIMAL, copies TRUNK 
to CONTEXT and CURRENT, and finally OUITs, which aborts execution 
and returns control to the console, "paren-paren-abort" 

((ERROR)) addr\cnt - 

Default error handler (initially placed in (ERROR) ). If QUIET is 
disabled, sounds the console's buzzer, outputs a CR LF and the most 
recently interpreted word (from POCKET ) followed by the string at 
the addr and cnt given. The data stack Is cleared. If BLK is non-zero 
(compiling from disc) , SCR is set to BLK , and R* is set to > IN , so 
that entry into the editor will point to the location of the error. 
Finally, QUIT is executed, aborting the current task and returning 
control to the console. See (ERROR) , POCKET , BLK , >IN , WHERE . 
"paren-paren-error" 

(+LOOP) n - 

The run-time procedure compiled by +LOOP. It increments the loop 
index by n and tests for loop completion. See +LOOP . 
"paren-plus-loop" 



(.") 



The run-time procedure compiled by ." . It transmits the following 
in-line text string to the selected output device. See ." 
"paren-dot-quote" 



(-5) 



Non-destructive stack display primitive. No CR before execution. 
Displays the contents of the stack using the following format: 

[d] c\b\a 
where d Is the stack depth, and a b and c are the top three stack 
Items. If d Is less than 3, only the stack Items present are displayed, 
"paren-dot-s" 
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(;CODE*) --- 

Stores the supplied cfa into the cfa of the latest word. The supplied 
cfa Is pointed to by the value on the return stack. 

(>CODE) 

Jumps to the address contained in the IP. Compiled by >CODE . 



(ABORT-) flag - 

Primitive routine compiled by ABORT" which precedes the In- line 
string literal. When executed, if flag is true, the string is typed to 
the console and executes ABORT . If flag is false, flag is dropped 
from the stack and execution resumes at the word following the 
string literal, "paren-abort-quote" 

(ABORT) - addr 

User variable containing the cfa to be executed by ABORT . This 
allows each task to have its own version of ABORT . "paren-abort" 

(DO) nl\n2 - 

The run-time procedure compiled by DO , which moves the loop control 
parameters to the return stack. See DO . "paren-do" 

(ERROR") flag - 

Compiled by ERROR" prior to an inline error message string. When 
executed, if flag is true, the most recently executed word (in POCKET 
) is displayed, followed by the inline error message string. If flag is 
false, flag is dropped from the data stack and execution continues 
beyond the string. See $L1T , (SLIT) , ERROR" , ABORT" . 
"paren-error-quote" 

(ERROR) - addr 

User variable containing the address of the word to be executed when 
an error is detected by the text interpreter, "paren-error" 
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(EXCPT) 

Code definition which copies the contents of the 68000 registers to 
the array REG.SET . The first 16 bytes on the return stack (hardware 
stack pointer) are also moved. This routine is called by all of the 
processor and unlmplemented instruction handlers during exception 
processing before they execute ABORT , providing a snapshot of the 
registers and the supervisor stack when the exception occured. The 
loadable utility .REGS ( MacFORTH Level 2) will give you a formatted 
dump of this information. Use the Motorola Processor Exeception 
Documentation to interpret the supervisor stack contents, 
"paren-except" 

(FIND) addrXvoc handle — [tokenXprec f lagXtrue] or [false] 

Searches the vocabulary for a match with the name found at addr. If a 
match is found, the token and precedence flag for the word are 
returned under a true flag, else a false flag is returned, "paren-f ind" 

(GET) addr- 

Multitasking stub for source compatibility with future CS1 MacFORTH 
products. 

(GETJILE) nl\n2\n3\n4\n5\ -- 

Standard file hook for uniform access to standard file package in 
MacFORTH Level 2. Unsupported in Level 1. "paren GET.FILE " 

(LINE) x\Y - 

QuickDraw line primitive. X and Y in local window native QuickDraw 
coordinates, unaffected by XYSCALE, XYPIVOT, or XY0R1GIN. "paren 
line" 

(LINE.TO) X\Y - 

QuickDraw relative line drawing primitive. X and Y in local window 
native QuickDraw coordinates, unaffected by XYSCALE, XYPIVOT, or 
XYORIGIN. "paren line-to" 

(LOOP) 

The run-time procedure compiled by LOOP which increments the loop 
index and tests for loop completion. See LOOP . "paren-loop" 

(MENU.SELECTION:) - 

Run time code for MENU.SELECTION: retained for clarity during tracing, 
"paren menu selection" 
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(MOVE) X\Y - 

QuickDraw line drawing primitive. X and Y in local window native 
QuickDraw coordinates, unaffected by XYSCALE, XYPIVOT, orXYORlGlN. 
"paren move" 

(MOVE.TO) X\Y - 

QuickDraw line drawing primitive. X and Y in local window native 
QuickDraw coordinates, unaffected by XYSCALE, XYPIVOT, orXYORIGIN. 
"paren move-to" 

(OF) nl\n2--[nl]or[] 

Run-time code compiled by OF. See OF. 

(ON.ERROR) - 

Pushes the recovery stack frame into the return stack. It then 
branches over the error recovery code. 

(PENSIZE) w/h - 

Sets PENSIZE regardless of XY scale, "paren pen size" 

(PUT.FILE) nl\n2\n3\n4~ 

Standard file hook for uniform access to the standard file package in 
MacFORTH Level 2. Unsupported In Level 1. "paren PUT.FILE" 

(R/W) - addr 

User Variable containing the address of the word which obtains a 
requested block from the disc, "paren-r-slash-w" 

(TEXTSIZE) size - 

Sets physical text size regardless of Y scaling, "paren textsize" 

(TRACE) 

Routine which executes the trace function of the compiler. Compiled 
by the interpreter before every token If the TRACE option switch is 
on. When the later executed. If the DEBUG option switch Is on, output 
Is tabbed to column 16, the stack Is displayed (using (.5) ). A CRLF Is 
output, and the name field of the following Inline token Is displayed. 
If the DEBUG option switch Is off, no output Is generated. See TRACE , 
DEBUG . "paren trace" 



MacFORTH Glossary Page 13-10 June 3, 1 984 



(TRACK.CONTROL) nl \n2\n3 - flag 

MacFORTH Level 2 controls primitive. Refer to the Level 2 
documentation. 

(WORD) charXaddr ~ addr 

Moves the string delimited by char from the input stream to addr. 
"paren-word" 

KONSTANT addr - 

Creates relocatable constant. When created, NEXT.PTR is subtracted 
from the stored 32 bit value. When the constant is later used, the 
saved value is summed with NEXT.PTR to produce the actual physical 
address. 

)U addr — n 

Converts the user area address given to the offset from the base of 
the user area. It is simply defined as: : )U STATUS - ; It is used 
to access another task's user area or the bootup literal area, 
"close-paren-u" 

* n1\n2--n3 

Leaves the product of (n1*n2). Error if the product is greater than 31 
bits plus sign. System response is to truncate the product to 32 bits 
with no error message, "times" 

*/ n1\n2\n3--n4 

Leaves the result of the product nl times n2 divided by n3. The result 
n4 is rounded toward zero. The intermediate product (n1*n2), is 
maintained as a 64-bit value for greater precision than the otherwise 
equivalent sequence n1n2*n3/ 

Error if division by zero, or quotient overflows, with NO system 
check, "times-divide" 

*/MOD n1\n2\n3~n4\n5 

Multiply nl by n2, divide the result by n3, leaving the remainder n4 
and quotient n5. A 64-bit intermediate product is used (as for */ ). 
The remainder has the same sign as nl. Error if division by zero, or 
quotient overflows with NO system check, "times-divide-mod" 

+ n1\n2~n3 

Add nl to n2 and leave the result n3. Error if sum overflows resulting 
in 32-blt truncated unnormalized sum with no system check, "plus" 
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+! nXaddr ~ 

Add n to the 32-bJt value at addr according to the convention for +. 
Error if the sum overflows with no system checl< (see + ). The error 
message ADDRESS ERROR TRAP indicates addr is odd (see ! ). 
"plus-store" 

+CARTESIAN wptr - addr 

Returns the address of a variable window record whose contents 
determine whether point coordinates for the window are to be 
interpreted in native Quicl<Draw or cartesian coordinates. When the 
variable is TRUE, all coordinates are expressed in Cartesian 
coordinates, "plus Cartesian" 

+FIND ~ [tol<en\f lag\true] or [false] 

Searches the dictionary for a match on the next word in the input 
stream. The next word in the input stream is extracted using WORD 
and placed in POCKET . If the word is found in the CONTEXT , CURRENT 
, or TRUNK vocabularies, the tol<en for the word, its precedence flag 
and true flag are returned. The precedence flag is true if the word is 
an immediate word and should be executed when compiling (ie. DO , IF 
, ." ). If the word is not found, a false flag is returned. See IMMEDIATE 
, CREATE , WORD , POCKET . "plus-find" 

+FOLLOWER n 1 - n 1 +FOLLOWER 

Returns the sum of n1 plus the offset to the user variable FOLLOWER 
from the base of the user area. 

+HBAR wptr ~ wptr+of fset 

Returns the address of a variable within a window record which 
contains the handle for a horizontal scroll bar control which is 
attached to the window. Refer to Level 2 controls documentation for 
further information. 

+LOAD relative scr* ~ 

Loads the screen number given relative to the current screen being 
loaded. For example, the sequence 1 +LOAD 
encountered while loading screen 100 would cause screen 110 to be 
loaded, "plus-load" 



MacFORTH Glossary Page 13-12 June 3, 1 984 



+LOOP n - 

Add the signed Increment n to the loop Index using the convention for 
+ and compare the total to the limit. Return execution to the 
corresponding DO until the new Index Is equal to or greater then the 
limit (for n>0), or until the new Index is less than the limit (for n<0). 
Upon exit from the loop, discard the loop control parameters from the 
return stack and pass control to the word following +LOOP . The error 
message CONDITIONALS NOT PAIRED Indicates the +LOOP was not 
matched with a DO . See DO . "plus-loop" 

+MAX.BLK* fob - addr 

Returns the address within the fob of the maximum variable 
containing the block number for the file. 

+ON.ACTIVATE wptr - addr 

Returns the address of a variable within the window record which 
contains the token to be executed when the window is activated. 

+ON.UPDATE wptr - addr 

Returns the address of a variable within the window record which 
contains the token to be executed when the window is updated. 

+POINT X1\YI\X2\Y2--X1+X2\Y1+Y2 

Adds two points. 

+PRINTER addrXcnt - 

Prints the contents of the string at addr for cnt bytes to the printer 
If the variable PRINTER is on, then to the display, "plus-printer" 

+REC.5IZE fcb - addr 

Returns the address within the fcb of the variable which contains the 
record size field for the file. 

+5CR* fcb ~ addr 

Returns the address within the fcb of the variable which contains the 
current screen number for the file. 

+THRU relative startVelatlve end ~ 

Load screens start through end relative to the current screen. For 
example, the sequence 

5 15+THRU 
encountered while loading screen 10 would cause screens 15 through 
25 to be loaded, "plus-thru" 
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+TYI5RECT text.record ~ addr 

Returns the address of the visible rectangle within the text edit 
record. Refer to level 2 TEEDIT Interface documentation for further 
details. 

+VBAR wptr — addr 

Returns the address of a variable within the window record which 
contains the handle for a vertical scroll bar control which Is attached 
to the window. Refer to Level 2 controls documentation for further 
information. 

+W.ATTRIBUTES wptr -addr 

Returns the address of the 16-bit variable within the window record 
which contains the window attributes to be assigned when the 



window is created: 


bItO 


CLOSE.BOX 


biti 


Not visible 


blt2 


SIZE.BOX 


bit3 


SCROLL.UP/DOWN 


blt4 


SCROLL.LEFT/RIGHT 


blt5 


TEXT.RECORD 


bits 6- 15 Reserved 



+W.BEHIND wptr - addr 

Returns the address of a variable within the window record which 
contains the wptr to place the new window behind when It is created. 
places it up front, -I places it at back. 

+W.LINK wptr ~ addr 

Returns the address of a variable within the window record which 
contains the address of the prior chronologically defined window. 
This linked list is traversed, during FORGET, to close any windows 
which are about to be forgotten. 

+W.TYPE wptr ~ addr 

Returns the address of a 16-b1t variable within the window record 
which contains the window type. Type Is a document window. 
Others Include dialog, with/without shadow, etc. 

+WB0UND5 wptr -addr 

Returns the address within the window record of a rectangle to be 
used as the window bounds when the window is created. 
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+WCB0UND5 wptr - addr 

Returns the address within the window record of the current content 
area rectangle for the window. This rectangle is kept current when 
the window is resized, and reflects the presence or absence of scroll 
bars. 

+WFILE.PTR wptr - addr 

Returns the address within the window record of a variable which 
contains the file number of file which Is associated with the 
specified window. 

+WLINE.HEIGHT wptr -addr 

Returns the address within the window record of a variable which 
contains the current LINE.HEIGHT . Windows are scrolled line.height 
bits up at the end of the screen. 

+WREFCON wptr - addr 

Returns the address within the window record of a variable which 
contains the window reference constant. This field normally contains 
the address of the handle for the current TE edit record. 

+W.TITLE wptr ~ addr 

Returns the address within the window record of a variable which 
contains the address of a string to be used as the window title. 
Executed when the window is created with ADD. WINDOW . 

+XYBIA5 wptr - addr 

Returns the address within the window record of a 32-blt variable 
which contains the Integer 16-blt sine and cosine of the current 
XYPIVOT angle. 

+XYOFFSET wptr - addr 

Returns the address within the window record of a 32-blt variable 
which contains the Y and X offset which is applied to all coordinates 
relating to the window. 

+XYPIYOT wptr - addr 

Returns the address within the window record of a 16-bit variable 
which contains the angle of rotation to be applied to all coordinates 
relating to the window. 



MacFORTH Glossary Page 13-15 June 3, 1 984 



+XYP05 wptr ~ addr 

Returns the address within the window record of a 32-blt variable 
containing the current XY position. This is used for all relative 
coordinates. 

+XY5CALE wptr - addr 

Returns the address within the window record of a variable which 
contains the current XYSCALE to be applied to all window coordinates. 

n- 
Allot 4 bytes In the dictionary, storing n there. An error Is reported If 
Insufficient object space Is available, "comma" 



Complies a string literal Into the dictionary. Extracts the following 

string, terminated by " (double quote), from the Input stream and 

emplaces It Into the dictionary preceded by Its count byte. For 

example: 

CREATE TEST.STRING ," THIS IS A TEST" TEST.STRING COUNT TYPE 

will output 

THIS IS A TEST 

This operator Is generally used to emplace string literals into the 

dictionary for words like ." , ABORT" , ERROR" , etc. "comma-quote" 

n1\n2~n3 
Subtract n2 from n1 and leave the difference n3. Error if the 
difference overflows. Returns a 32-bit value similar to that of the 
case of overflow from addition with no system check. See + . "minus" 



— > 



Continue Interpretation on the next sequential block. May be used In a 
colon or code definition that crosses a block boundary, "next-block" 

■1 -1 

Constant containing the value -1. 

2 - -2 

Constant containing the value -2. 

-3 - -3 

Constant containing the value -3. 
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■4 -- -4 

Constant containing tne value -4. 

■FIND — [tokenXf lagXtruel or [false] 

Searches the dictionary for a match on the next word In the input 
stream. Extracts the next word in the input stream (via WORD), 
placing It in POCKET . If the word is found in the CONTEXT or TRUNK 
vocabularies, the token for the word, its precedence flag, and a true 
flag are returned. The precedence flag is true if the word is 
Immediate and should be executed when compiling (ie. DO , IF , ." ). If 
the word is not found, a false flag is returned. 
See IMMEDIATE , INTERPRET . 
"dash-find" 

-FOUND token - 

Reports an error " ?'" if token is zero. 

-KEYBOARD -n 

Constant mask which allows all but keyboard events to 

be received. This value is ended with the contents of EVENTS if a 

keystroke already exists prior to execution of DO.EVENTS allowing 

type-ahead. 

"minus-keyboard" 

-LATEST 

Removes latest token, name, and object space from current 

dictionary, it ignores smudge bit. 

"minus-latest" 

-POINT X 1 \y 1 \x2\y2 ~ x 1 -x2\y 1 -y2 

Subtracts two points. See +POINT . 

-TEXT addr I \cnt\addr2 -flag 

Compares the two strings at addrl and addr2 for cnt bytes. The flag 
returned is zero if the strings are equivalent, otherwise the flag 
equals the difference between the last two characters compared, as 
follows: addrl(i) - addr2(1) 
"dash-text" 
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-TRAILING addr\cnt1 --adclr\cnt2 

Strips trailing blanks from the string at addr. Adjust the character 
count cntl of a text string beginning at addr to omit trailing blanks 
(1e. the characters from addr+cntl to addr+cnt2 are blanks). Error If 
cntl Is negative with no system check, 
"minus-trailing" 

n~ 
Dlsplays n. n is converted according to BASE in a free format field 
with one trailing blank. Displays a negative sign if n is negative, "dot" 



Outputs a string of text delimited by " . Executed or compiled in the 

form 

." aaaaaaaa" 

Accept the following text from the input stream, terminated by " 

(double-quote). If executing, transmit this text to the selected 

output device. If compiling, compile so that later execution will 

transmit the text to the output device. Up to 255 characters are 

allowed in the text. The error message MISSING STRING DELIMITER 

indicates the input stream was exhausted before the delimiting 

double quote was encountered, "dot-quote" 

The double quote delimiter is pronounced "quote" 

ABORT n - 

Prints the number n In hexadecimal, and aborts. 

DATES - 

Displays the current date from the internal clock in the following 
format: MM/DD/YY 

.FILE.ERROR error number — 
See the File System Glossary. 

.R nXwidth ~ 

Displays n right-justified. The field is width characters wide, and n 
is displayed according to BASE. If width Is less than 1, no leading 
blanks are supplied, "dot-r" 
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.5 

Non-destructlvely displays the contents of the stack. The number of 

Items on the stack Is first displayed, enclosed In brackets, followed 

by the top three stack Items (the top stack Item Is furthest to the 

right) after a carriage return. For example, If you enter 

1 23 .5 

you will see 

[3]\ 1 \2\3 

If you then add another stack Item (say 4 for example), you will see 

[4]\2\3\4"dot-s" 

.TIME$ 

Displays the current time as read from the internal clock in the 
following format: HH:MM:SS XM 

.TYPE addrXcnt -- 

Default Macintosh console output operator. Scrolls up at bottom of 
screen. 

/ n1\n2-n3 

Divide nl by n2, leaving the quotient n3. n3 is rounded toward zero 
(truncated). Error on division by zero with no system check, "divide" 

/MOD n 1 \n2 ~ remainderXquotient 

Divide nl by n2 and leave the remainder under the quotient. The 
remainder has the same sign as nl. Error on division by zero with no 
system check, "divide-mod" 

-0 

Constant containing the value 0. 

0< n ~ flag 

The flag is true if n is less than zero (negative), "zero-less" 

0= n — flag 

The flag is true if n Is equal to zero, "zero-equals" 

0> n ~ flag 

The flag is true if n is greater than zero, "zero-greater" 
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OBRANCH flag - 

The run-time procedure used for conditional branching, if flag Is 
false (zero), the following in-line parameter Is added to the 
interpreter pointer to branch ahead or back. Compiled by IF , UNTIL , 
and WHILE . "zero-branch" 

OMAX n - [n] or [0] 

Code routine which returns the maximum of n or 0. "zero-max" 

1 -1 

Constant containing the value 1. 

1 + n - n+ 1 

Increments the top stack item by one. 

1- n~n-l 

Decrements the top stack item by one. 

10+ n~n+10 

Increments the top stack item by ten. 

10- n~n-10 

Decrements the top stack Item by ten. 

12H0UR5 -n 

Constant returning the number of seconds in 1 2 hours. 

16* n — n*l6 

Multiplies the top stack item by sixteen. 

16+ n~n+16 

Increments the top stack item by sixteen. 

16- n ~ n- 1 6 

Decrements the top stack item by sixteen. 

16/ n~n/16 

Divides the top stack Item by sixteen. 

1DAY -n 

Constant returning the number of seconds in one day. 
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1H0UR -n 

Constant returning the number of seconds in one hour. 

2 --2 

Constant containing the value 2. 

2! nl\n2\aclclr- 

Stores n2 at addr, nl at addr+4. 

2* n ~ n*2 

Multiplies the top stack item by 2. 

2+ n ~ n+2 

Increments the top stack item by 2. 

2- n - n-2 

Decrements the top stack item by 2. 

2/ n ~ n/2 

Divides the top stack item by 2. 

2m addr--n1\n2 

Fetches n2 from addr, nl from addr+4. 

2DR0P nl\n2-- 

Drops n 1 and n2 from the stack. 

2DUP n1\n2-n1\n2\nl\n2 

Duplicates nl andnZ 

20YER n 1 \n2\n3\n4 ~ n 1 \n2\n3\n4\n 1 \n2 

Copies nl and n2 to the top of the stack. 

25WAP n 1 \n2\n3\n4 ~ n3\n4\n 1 \n2 

Swaps nl,n2 with n3,n4. 

2W>MT nl - 

Macintosh Tooltrap interface word. See Advanced Topics toolbox 
interface section. 

3 -3 

Constant containing the value 3. 
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3+ n ~ n+3 

Increments the top of the stack by three. 

3- n ~ n-3 

Decrements the top of the stack by three. 

4 -A 

Constant containing the value 4. 

4* n — nM 

Multiplies the top of the stack by four. 

4+ n — n+4 

Increments the top stack Item by 4 

4- n ~ n-4 

Decrements the top stack Item by 4 

4/ n ~ n/4 

Divides the top stack item by 4. 

5+ n ~ n+5 

Increments the top stack Item by 5. 

5- n ~ n-5 

Decrements the top stack Item by 5. 

6+ n ~ n+6 

Increments the top stack Item by 6. 

6- n ~ n-6 

Decrements the top stack Item by 6. 

7+ n ~ n+7 

Increments the top stack item by 7. 

7- n ~ n-7 

Decrements the top stack item by 7. 

8* n — n*8 

Multiplies the top stack Item by 8. 
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8+ n — n+8 

Increments the top stack Item by 8. 

8- n -- n-8 

Decrements the top stack item by 8. 

8/ n ~ n/8 

Divides the top stack item by 8. 



Begins compilation of a new definition. A defining word used in the 

form: 

: <name> . . . ; 

Set CONTEXT to CURRENT and create a dictionary entry for <name> in 

the CURRENT vocabulary. Words thus defined are "colon definitions' 

and the compilation address of subsequent words from the input 

stream which are not immediate are compiled into the dictionary to 

be later executed when <name> is executed. IMMEDIATE words are 

executed as encountered. Words encountered that are not found in the 

dictionary (CONTEXT and TRUNK vocabularies) cause compilation to 

stop with a question mark printed after the offending word. The 

warning message: 

ISN'T UNIQUE 

indicates that a previous definition for <name> exists, "colon" 



Terminate a colon definition and stop compilation. The error message 
DEFINITION INCOMPLETE indicates the stack depth changed within the 
current colon definition, "semicolon" 

< n1\n2--flag 

Returns a true flag if n1 is less than n2. "less-than" 



<# 



Initialize pictured numeric output. The following group of words are 
used to convert a number to its ASCII string equivalent: 
<* ^> * *S HOLD SIGN 
"less-sharp" 
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<W* addr ~ n 

Fetches the l6-b1t contents at addr and sign extends It to 32 bits. 
An address error trap will result If add is odd. Use <W@> for odd or 
even addresses, 
"extended-word-fetch" 

= nl\n2~flag 

Returns a true flag If nils equal to n2. "equals" 

=CELL5 n1 -n2 

Ensures n1 Is even by adding one to It If It is odd. "equals-cells" 

=DROP nl\n2-[n1\n2]or[nl] 

Drops n2 if nl=n2. "equals-drop" 

> nl\n2~flag 

Returns a true flag if n1 is greater than n2. "greater-than" 

>FCB *** Refer to the File System chapter glossary ***** 

>IN -addr 

User variable pointing to the current character in the input stream. 
Error if the value stored is outside the range to 1023 with no 
system response. See : WORD ' ( ." and FIND . "to-in" 

>JSR addr — 

Jumps to the assembly code subroutine at addr. Registers A0-A2, 
D0-D3 are available; A3-A7, and D4-D7 should be saved and restored 
by the assembly routine if they would be modified. The JSR 
instruction places the address (containing NEXT ) on the return stack 
(A7). Return to FORTH via an RTS instruction. NOTE: MacFORTH 
expects to run in supervisor state, NOT user state, "to-j-s-r" 

>LIST< 

Indirectly references the word to execute at the top of every listed 
screen. Used to time and date stamp listings. 

>R n - 

Pushes the top stack item onto the return stack. Be aware that DO . . 
. LOOP affects the return stack. (DO pushes 2 items, LOOP pops them). 
Error if not balanced inside of a colon definition or inside a DO . . . 
LOOP structure with a matching R> (see R) with an unpredictable 
system response, "to-r" 
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>RECT X 1 \y 1 \x2\y2 ~ RB\LT\SP@ 

Returns address within stack of reformatted rectangle xl\y1\x2\y2. 
Rectangle coordinates are translated and offset according to 
XY5CALE, XVPIVOT. and XYOFFSET before reformatting occurs. 
Rectangle Is In QuickDraw topjeft, bottom, right format. 

>5Y5.WIND0W -- 

Directs output to system window. 

>W!< n\addr ~ 

Stores the 1 6 bit value n at addr. Addr may be an odd address. 

>W»< addr ~ n 

Fetches the 1 6 bit value at addr. Addr may be an odd address. 

? addi — 

Displays the 32-b1t value at addr. "question mark" 

7ALIGN 

Forces the dictionary pointer to an even address. The user variable DP 
Is Incremented by one If It Is odd. "query-align" 

7BL0CK5.FILE file^-flag 

Flag is true if File* Is a BLKS type file. 

7C0MP 

Verifies compilation state. Issue the error message COMPILATION 
ONLY! USE ONLY IN A DEFINITION If STATE does not indicate 
compilation mode, "query-comp" 

7C5P 

Verifies the stack did not change during compilation. Issues the error 
message DEFINITION INCOMPLETE ! if the value in the user variable 
CSP is different from the stack position. See CSP . "query-c-s-p" 



7DAY5 nl-n2 

Converts n1 seconds into n2 days, nl is divided by the number of 
seconds In one day, leaving the result n2. 

7DUP n -- [n\n] or [n] 

Duplicate n if it is non-zero, "query-dup" 
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?EOF '*'* Refer to the File System chapter glossary **** 

7EVENT recordXmask ~ event code 

Copies next event that passes mask to record. Event is not removed 
from the event queue, "query-event" 

7EXEC 

Verifies execution state. Issue the error message EXECUTION ONLY 
if STATE does not indicate execution mode, "query-exec" 

7FILE.ERR0R "''Refer to the File System chapter glossary.'** 
7FILE5 '*'* Refer to the File System chapter glossary *^ 

7HEAP.SIZE - size 

Returns total amount of space available in heap, including any grow 
region. Refer to Apple Developer's documentation for further detail 
Reference: FreeMem 

7IN.C0NTR0L -flag 

Returns a true flag if most recent MOUSE.DOWN even occurred in a 
control attached to the currently active window. The variable 
THIS.CONTROL contains the handle to the affected control. The 
variable THIS.PART contains the relevant control part code. 

7KEY5TROKE ~ [keyXtrue] or [false] 

Checks for a keystroke from the Mac keyboard. Returns a key under a 
true flag if a key was pressed, otherwise just returns a false flag. 

7L0ADING - 

Verifies loading from disc. Issue the error message: 

CANT USE FROM TERMINAL I 

if a word is executed from the terminal which should only be executed 

from disc, "query- loading" 

70PEN *** Refer to the File System chapter glossary *^ 

7PAIR5 n1\n2 - 

Verifies conditionals were paired in the latest definition. Issue the 
error message CONDITIONALS NOT PAIRED if n1 is not equal to n2. 
The message indicates compiled conditionals do not match, 
"query-pairs" 
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7PUNCT addr - flag 

Checks for valid punctuation. Returns a true flag If the ASCII 
character at addr is one of the following: , . / : If the character Is 
not one of the above, a false flag Is returned, "query-punct" 

?ROori 

Reports the amount of space available in the heap, object and 
vocabulary memory areas. 

75EC0NDS nl-n2 

Converts n1 seconds into n2 seconds since midnight of the current 
day. nl is divided by the number of seconds in one day, leaving the 
remainder n2. 

750UND - flag 

Returns a true flag if sound driver is active asynchronously. 

75TACK 

Checks for underflow of the parameter stack. Issue the message 

STACK EMPTY! if the parameter stack underflows. 

"query-stack" 

7TERMINAL - flag 

Returns a non-zero flag if a key has been pressed, otherwise false, 
"query- terminal" 

7TRACE 

Compile (TRACE) into the dictionary if the TRACE option switch is 
enabled . "query-trace" 

7W0RD char - addr 

Parses a string from the input stream. Performs the same function as 
WORD (see WORD ), except it aborts with the error message: 
MISSING STRING DELIMITER 

if the input stream is exhausted before the delimiter was 
encountered, "query-word" 

9 addr ~ n 

Returns the 32-b1t contents of addr. The error message "ADDRESS 
ERROR TRAP" Indicates addr was odd. If you need to fetch data from 
odd addresses, use CMOVE or <W@> . 
"fetch" 
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•P addr ~ n 

Returns the 32-blt contents of the contents pointed to by addr. The 
error message "ADDRESS ERROR TRAP " Indicates addr or Its contents 
were odd. 
"fetch-fetch" 

©CLOCK - n 

Returns the number of seconds since 1 2:00 am 1 /0 1 /04 as read from 
the internal clock. 

©EVENT recordXmask ~ event code 

Copies next event from event queue to record. Returns event code if it 
applies to current window, otherwise 0. 

©FILE.NAME ** Refer to the File System chapter glossary «* 

©INIT 

Asks for input of the user's initials. The message: 
ENTER YOUR INITIALS [XXX] -> 
is displayed and you (or any user) can input up to 3 initials. 
©MOUSE - point 

Returns current location of mouse in local coordinates. 

©MOUSE.DN -point 

Returns location of where the mouse last went down (button pressed) 
in local coordinates. 

©MOUSEXY ~x\y 

Returns mouse position in userwindow coordinates. Sensitive to 

cartesian flag, XYSCALE, XYOFFSET. 
©PEN - x\y 

Returns current pen position in local coordinates to the currently 
active window. 

©PEN5TATE ~ 20 bytes (5 stack items) 

Fetches the current pensize, penpat, penloc, and penmode to the stack, 
(see IPENSTATE) 

©POINT ( addr - x\y ) 

Fetches 32 bit value from addr and unpacks x,y to stack. 
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©RECT addr ~ t\l\b\r 

Unpacks rectangle at address. Top Left Bottom Right are pushed Into 
stack. 

»5R - n 

Returns the contents of the 68000 hardware status register. This 
16-bit value is contained in the least significant bits of n. 
"fetch-s-r" 

ABORT 

Aborts the current task. Clears the data and return stacks and returns 
control to the console in execution mode. 

ABORT" flag - 

Aborts the current task with the supplied message if flag is true and 
RETRY is zero. Used in the form: 

ABORT" <user message)" 
Compiles (ABORT") followed by <user message) preceded by its count 
byte. At execution time, if flag is true, <user message) is displayed 
in the MacFORTH window, and ABORT is executed. If flag is false, no 
action is taken. If RETRY is non-zero, error recovery occurs at the 
stack frame in the return stack pointed at by RETRY . 
See ABORT , (ABORT") , RETRY . "abort-quote" 

ABORT.EVENT -n 

Constant event.code returned by DO.EVENTS on an abort event. 

AB5 n1~n2 

Returns n2 as the absolute value of n1. Error occurs when the 
argument is the most negative 32-bit number. That argument is 
returned unchanged with no error message, "absolute" 

ACTIVATE.EVENT -n 

Constant event code returned by DO.EVENTS on an activate event. 

ADD.BLOCKS **»* Refer to the File System chapter glossary »** 

ADD.WINDOW wptr - 

Builds window from w.title, w.bounds, w.type, and w.attrlbutes, and 
links It into window list and displays It If visible. W.BEHIND 
determines where window will appear in the window list 
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AGAIN 

Marks the end of an infinite loop structure. Causes an unconditional 
branch back to the start of a BEGIN . . . AGAIN loop construct. It Is 
equivalent to BEGIN ... UNTIL See BEGIN , UNTIL . 

ALIT ~ address 

Pushes the sum of the next 32-b1t value in the interpretation stream 
and NEXT.PTR into the stack. Advances over the value. 

ALLOCATE f1les1ze\f1le*-- 
See File System glossary. 

ALLOT n - 

Increments the dictionary pointer by n. Aborts if object area is too 
small to contain n additional bytes. 

AND nl\n2--n3 

Returns n3 as the bitwise logical AND of n1 and n2. 

APLAY addr - 

Passes addr+2 to Macintosh sound driver. Addr contains the 1 6-bit 
size of the waveform record at addr+2. Sound is generated 
asynchronoously. 

APPEND tokenXstr.addr — 

Appends string with token to current vocabulary. Error message is 
generated if insufficient space is available in the vocabulary. Resize 
the vocabulary with RESIZE.VOCAB . 

APPEND.BLOCKS *of blocksXfile* - 
See Editing Programs glossary. 

APPEND.ITEM5 1tem$\menu1d -- 

.Appends elements in 1tem$ ( separated by ';") to the specified menu. 
See Menu Chapter of the manual. 

APPLE.MENU I - 

Installs the Apple desk accessory menu on the Menu Bar. 

ARC X 1 \y I \x2\y2\sa\ca\[pattern addr]\mode ~ 

Draws ARC within the recangle x1ylx2y2 starting at angle sa and 
ending at angle ca. PATTERN.ADDR required for the PATTERN mode. 
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ASSIGN nie$\f11e*-- 
See File System glossary. 

AUTO.KEY - n 

Constant event code returned by DO.EVENTS on an auto key (repeat) 
event. 

AXE 

Looks up and removes the next word in the Input stream from the 
current vocabulary. Vocabulary is closed up to recover space. Object 
space for word is not affected. 

B/BUF - n 

Returns the number of bytes per block buffer.( 1 024) 
"b-slash-buf" 

BACK addr - 

Calculate the backward branch offset from HERE to addr. It is then 
compiled into the next available 16-bit memory cell in the dictionary. 

BACKPAT addr - 

Sets QuickDraw background patternto supplied pattern address. 

BASE - addr 

User variable containing the current I/O numeric conversion base. 
Error if the value in BASE is outside the range 2 through 70 with no 
system check. 

BEGIN 

Marks the start of a loop structure for repetitive execution. Used in a 
colon definition in one of the following forms: 

BEGIN . . . UNTIL BEGIN . . . AGAIN 

BEGIN ... WHILE .. . REPEAT 
The words after UNTIL and REPEAT (remember, BEGIN ... AGAIN is an 
endless loop ~ see AGAIN ) will be executed after the loop 
terminates. The error message: 

DEFINITION INCOMPLETE I 
indicates the BEGIN was not matched with an UNTIL , AGAIN , or WHILE 
... REPEAT sequence. 

BEHEAD token - 

Removes the name and token fields for the supplied token from the 
current vocabulary. 
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BL --32 (decimal) 

Returns the value for the ASCI I blank character. "b-V 

BLACK - addr 

Returns the address of the black pattern. 

BLANKS addr\cnt ~ 

Fills memory at addr for cnt bytes with ASCII blanks. 

BLK - addr 

User variable containing the block currently being interpreted as the 
input stream. If BLK is zero, the input stream is coming directly from 
the terminal, "b-l-k" 

BLOCK block* ~ addr 

Returns the buffer address of the requested block number. If the 
requested block is not already in a block buffer, it is transferred from 
mass storage into the least recently accessed buffer. If the previous 
data In that buffer has been UPDATEd, It is written out to mass 
storage before the new block is read in. Only data within the latest 
block referenced by BLOCK is valid due to sharing of the block buffers. 

BLOCK-FILE *** Refer to the File System chapter glossary *** 

BOLD -01 

Constant bit mask for bold text attribute. 

BOOLEAN n ~ true or false 

Converts n to a true flag (-1) if n Is non-zero. 

BRANCH 

The run-time procedure to unconditionally branch. An In- line offset 
is added to the interpreter pointer, IP , to branch ahead or back. 
BRANCH is compiled by ELSE , AGAIN , and REPEAT . 

BRING.TO.FRONT wptr- 
Brings window to FRONT. 

B5 —08 (decimal) 

Returns the value for the ASCII backspace character, "b-s" 
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BUFFER block* ~ buffer addr 

Returns the addr of an available block buffer for the block number 
given. 

BYE 

Exits MacFORTH, Launching Finder. 

C! charXaddr ~ 

Stores the 8-bit value char at addr. "c-store" 

C, char — 

Emplaces char into the dictionary. Stores the 8-bit value into the 
dictionary at the current dictionary pointer value, and increments the 
dictionary pointer by 1. 

C/L - n 

Returns the number of characters per line in a block of source code. 

(64) 

"c slash 1" 

C© addr ~ char 

Returns the 8-b1t value char located at addr. "c-fetch" 

CARTESIAN (addr -) 

Returns the address of the Cartesian coordinate flag. When this flag is 
on, coordinates are interpreted in Cartesian coordinates ( positive y up 
). When flag is off, Native QuickDraw coordinates ( negative y up ) are 
used. Refer to the graphics section for a complete discussion of this 
feature. 

CASE n ~ n 

narks the beginning of a case statement. Used in the form: 
CASE ... X OF ... ENDOF 
Y OF ... ENDOF 
ENDCA5E 

CENTER ( - ) 

Sets the graphics XYOFFSET to 1/2 MAX.X , 1/2 MAX.Y, the center of the 
current window. 

CHARWIDTH char - width 

Returns width in pixels for char in current font. 
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CHECK.BOX (n 1 \n2\n3\n4\n5 -) 

Check box control definition word. Unsupported in Level 1. Refer to 
Level 2 controls documentation. 

CIRCLE x\y\rad1us\[pattern]\mode — 

Draws circle of radius at XY within current window according to mode. 
[PATTERN] present for pattern mode only 

CLEAR - 2 

QuickDraw shape mode attribute shape will be filled in with background 
pattern. 

CLIP>CONTENT wptr- 

Clips all drawing in window to the content region. Controls will not be 
updated. Refer to NO. CLIP . 

CLOSE file* - 

See File System glossary. 

CL05E.ALL *»* Refer to the File System chapter glossary ** 

CLOSE.BOX - n 

Constant containing bit mask for close box attribute in window 
attribute field. 

CLOSE.WINDOW wptr- 

Closes window specified by wptr. All window-related heap data 
structures are returned to the heap. Window is removed from window 
linked list, if you are unable to close SYS.Window use HIDE. WINDOW . 

CMOVE src addrXdest addrXcnt ~ 

Moves cnt bytes from srce addr to dest addr. The transfer begins In low 
memory and moves toward high memory (ie. the byte at src addr is 
moved to dest addr, then the byte at src addr+l Is moved to dest 
addr+1, etc.). Error If the count is less than one; the system drops the 
parameters from the stack and no movement occurs, "c-move" 

CMOVE> src addrXdest addrXcnt — 

Moves cnt bytes from src addr to dest addr. Starts at the end of the 
string and proceeds toward low memory, "c-move-up" 
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CNT -- addr 

User variable containing the total count of characters transferred by 
TYPE or EXPECT . Immediately following execution of EXPECT , CNT 
contains the actual number of bytes received, "c-n-t" 

CNTR - addr 

User variable containing the current count of characters to be 
transferred. This number counts toward for both input and output, 
operations, "c-n-t-r" 

COL - addr 

User variable containing the current output column position. You may 
examine and alter this user variable to control display formatting, 
"col" 

COMMAND.KEY -n 

Constant event.code returned by DO.EVENTS when a menu item is 
selected from the keyboard. 

COMPILE 

Used to compile the tol<en for a word into the dictionary. When a word 
containing COMPILE is executed, the token for the word following 
COMPILE in the defintion is compiled into the dictionary. An unchecked 
error exists if the word following COMPILE is not found in the 
dictionary or convertible to a number. 

COMPILING - flag 

Returns a true flag if STATE is non-zero. STATE = non-zero indicates 
compilation mode, STATE = zero Indicates execution mode. 

CONDENSED - 32 

Constant bit mask for condensed text attribute. 

CONFIGURE.PRINTER *stop bits\parity\* data bits\ baud rate 

Used to custom configure the printer port for non-lmagewriter 
printers. Refer to the Printer chapter for more information. 

CONSOLE - addr 

Returns the address of the user variable which contains the address of 
the current console device table. 
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CONSTANT n - 

Creates a constant with value n. A defining word used in the form: 
n CONSTANT <name> to create a dictionary entry for <name>, which 
when later executed will leave n on the top of the stack, n is compiled 
into the pfa of <name>. 

CONTEXT - addr 

Returns the address of the user variable which contains the handle for 
the vocabulary where dictionary searches are to begin during 
interpretation of the input stream. 

CONVERT n I \addr I - n2\addr2 

Converts the ASCII string at addrl + l to its binary equivalent. The 
number is accumulated into n1 and returned as n2. Addr2 is the address 
of the first unconvertible character. 

COPY src blk*\dest blk* ~ 

Copies the src blk* into dest blk*. 

COS ANGLE ~ cosine * 1 0000 

Returns integer cosine of angle * 10000 (4 digits precision). 

COUNT addr ~ addr+ 1 \cnt 

Returns the address and count of the text string at addr+1. The count 
byte is at addr and text is at addr+ 1 on. The range of n is - 255. 

CR 

Emits a CR LF to the current output device, "c-r" 

CREATE 

A defining word to create a dictionary entry for the name given. Used 
In the form: 

CREATE <name> 
to create a dictionary entry for <name>, without allocating any 
parameter field memory. When <name> is later executed, the address of 
<name>'s parameter field is left on the stack. If the UNIQUE.MSG Is on 
and the word already exists In the CONTEXT or TRUNK vocabularies, the 
message "ISNT UNIQUE" is displayed. See UNIQUE.MSG 

CREATE.BLOCKS.FILE ** Refer to the File System chapter glossary *« 
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CREATE.FILE nie*-- 

See File System glossary. 

CRLF - addr 

Returns the address of a literal string containing a CRLF sequence. Used 
in the form: CRLF 2 TYPE to output a CR LF sequence. "c-r-l-f" 

C5P ~ addr 

Returns the address of the User Variable which temporarily holds the 
value of the stack pointer during compilation for error checking, 
"c-s-p" 

CURRENT - addr 

User variable which contains the handle for the vocabulary into which 
newle created words are appended. This is the second vocabulary to be 
searched during a dictionary search (after CONTEXT ). 

CURRENT-FILE ** Refer to the File System chapter glossary ** 

CURRENT.POSITION file* - current file position 
See File System glossary. 

CURSOR - addr 

Variable containing address of current cursor array. 

CUR50R.CHAR - addr 

Returns the address of a variable containing the text font for the 
cursor symbol in the first 16 bits and the character code for the 
symbol in the second 1 6 bits. 

DAY5> *days since 01/01 /84 — year\days\month 

Converts days to year, days, month. 

DEALLOT token - 

Deallots object space for and above token. 
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DEBUG - addr 

User Variable containing flag which Indicates debug mode. 

DEBUG ON 
sets the system into DEBUG state. 

DEBUG OFF 
clears DEBUG state. When DEBUG Is ENABLED , Items left on the stack 
during execution are displayed with .S , and words being executed have 
their name and stack Implications displayed, If they where compiled 
with TRACE mode set. 

DECIMAL 

Set the I/O numeric conversion base to ten. See BASE . 

DEFAULT.ACTIVATE - 

Default activate function for all defined windows. Beeps on activate, 
(mouse down) nothing on deactivate. 

DEFINITIONS - 

Determines the vocabulary new definitions are compiled in. Set 
CURRENT to the CONTEXT vocabulary so that subsequent definitions will 
be created in the vocabulary previously selected as CONTEXT. 

DELETE file*-- 

See File System glossary. 

DELETE.BLOCKS ** Refer to the File System chapter glossary ** 

DELETE.I1ENU menuid 

Deletes menu menuid from menubar, redraws menubar. 

DEPTH - n 

Return the number of stack Items (32-blt values) currently on the stack 
(before n was added). 

DEVICE.CONTROL parm 1 \parm2\cmd\f cb 

Stores: 16BitCMD at FCB+26 

32 Bit PARM 1 at FCB+28 

32 Bit PARM2 at FCB+32 

at FCB+36 

Issues: OS CONTROL TRAP with FCB . 
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DEYICE.5TATU5 cmdNfcb ~ parm 1 \parm2 
Stores: 16 Bit CMD at FCB+26 
Issues: 05 STATUS TRAP with FCB 
Fetches: 16 Bit PARM1 from FCB+32 
32 Bit PARM2 from FCB+28 

DFLT.CONTROL - 

Default word used to handle control characters on input and output for 
special console devices. 

DFLT.WINDOW.TAIL - addr 

Array containing the default values for the MacFORTH extension to the 
standard window record. 

DIGIT charXbase ~ [nXtrue] or [false] 

Convert the ASCII character char, using the base given, to its binary 
equivalent. If the conversion was valid, n is left as the binary 
equivalent under a true flag, otherwise only a false flag is returned. 

DIR drive ^-- 49'ER FiOP 

Prints catalog for media in drive. NORTH TAHOE HIGH SCHOOL 

P. O. BOX 5099 

DIRECTORY -- addr TAHOE CITY, CA 95730 

Returns the address of the user variable which contains the disc 
directory load screen. 

DISCARD.UPDATE5 - 

Discards any pending update events for the current window. Used to 
eliminate double flash at window activation if ACTIVATE code redraws 
the window contents anyway. 

DISK - addr 

Variable containing DISK resource variable. 

DI5K.EVENT - n 

Constant event.code returned by DO.EVENTS on a disk inserted event. 

DI5P05E.C0NTR0L n - 

Disposes control. Unsupported in Level 1. Refer to Level 2 controls 
documentation. 
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DKGRAY - addr 

Returns the address of the dark grey pattern. 

DO upper limitMower limit ~ 

Marks the beginning of a finite loop structure. Used in a colon definition 
in the form: DO ... LOOP or DO ... n +LOOP Begins a loop which will 
terminate based on the upper and lower limits given. See LOOP and 
+LOOP . DO .. LOOP'S may be nested as long as each DO is matched with a 
correspond- ing LOOP or +LOOP within the same colon definition. The 
error message DEFINITION INCOMPLETE I indicates a DO was not 
matched with a corresponding LOOP or +LOOP . 

DO.EVENTS - event code 

Removes next event from the event queue. Executes any supplied default 
token in the events list, and returns the event code. Refer to manuals 
for discussion of event codes. 

D0E5> 

Defines the run-time action within a high-level defining word. Used in 
the form: 
: <name> ... CREATE ... DOES> ... ; 

It marks the termination of the defining part of the defining word 
<name> and begins the definition of the run- time action for words that 
will later be defined by <name>. On execution of a word defined by 
<name>, the words between DOES> and ; will be executed, with the 
parameter field address of the new word on the stack, "does" 

DOT ( x\y ~ ) 

Pen is placed at X,Y . Pen pattern, size, and mode determines effect on 
dots below and to the right of X,Y. X,y are rotated, scaled and translated 
within the window. 

DOWN.BUTTON -n 

Part code for down button. Refer to Level 2 controls documentation. 

DP ~ addr 

User variable containing the current value of the dictionary pointer. 
This value may be read using HERE and altered using ALLOT . See HERE 
and ALLOT . "d-p" 

DPL - addr 

User variable containing the number of places after the decimal point 
for numeric input conversion. " 
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DRAW.CHAR char - 

Draws character at current pen position with current text transfer 
mode In current textstyle textfont and textslze. 

DRAW.C0NTR0L5 wptr- 

Draws controls associated with window. Refer to Level 2 controls 
documentation. 

DRAW MENU.BAR - 

Redraws menu bar from current menu list. Execute this word after 
adding or deleting items to or from the menu list. 

DRAW.TO x\y - 

Draws to the supplied XY position. Dots to the right and below the pen 
are modified according to the current pen size, shape, pattern, and 
mode. 

DRAWSTRING addr- 

Draws string at addr with count in first position at current pen 
position. Uses current text settings. 

DROP n - 

Drop the top stack item. 

DRVR.EVENT - n 

Constant event code returned by DO.E VENTS on a DRIVER event 

DUP n - n\n 

Duplicate the top stack item, "dupe" 

DUP>R n - n 

Duplicates the top item on the stack and places it on the top of the 
return stack. 

EJECT drive* ~ 

Ejects media in drive. 
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ELSE 

Marks the beginning of the "false portion" of a conditional structure. 
Used In a colon-definition in the form: 

IF ... ELSE ... THEN 
If the conditional for the IF is true, when the ELSE is encountered, it 
passes control to the word following THEN . If the conditional for the IF 
is false, control is passed to the word following ELSE. The error 
message: 

DEFINITION INCOMPLETE I 
Indicates the control structure was missing Its THEN . The error 
message: 

CONDITIONALS NOT PAIRED 
indicates the control structure was missing its IF . 

EMIT char ~ 

Transmit char to the current output device (this is usually the active 
window). 

EMPTY 

Removes all words and vocabularies above the currently specified 
task-dependent FENCE from the dictionary. Tasks which are forgotten 
will be unlinked from the dispatch queue. See (FORGET), FENCE , 
SET.FENCE 

EMPTY-BUFFERS - 

Clears contents of disc buffers, marking all buffers as inactive. 

ENCLOSE addrXdelim — addr\offsetl \offset2\offset3 

Text parsing primitive. Given an address to parse from and a delimiter, 
this operator skips over leading delimiters returning address under 
offset to the first non-delimiter (offset 1), under the offset to the last 
non-delimiter (offset2), under the offset to the following delimiter 
(offset3). The enclosed test starts at addr+offset2. Parsing for the 
next word should begin at 3ddr+off3et3. A null (zero) character always 
acts as a delimiter regardless of the specified delimiter. 

ENDCASE n - 

Terminates a case statement. Used in the form: CASE ... X OF ... 
ENDOF ENDCASE Completes the case statement by dropping n and 
resolving all unresolved branch addresses (left on the stack by ENDOF) 
to pointer after ENDCASES . Executes during compil- ation. 
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ENDOF 

Terminates a conditional branch within a case statement. Used In the 
form: CASE... X OF ...ENDOF ENDCA5E 

ENTER.FLAG - addr 

Variable containing the enter key flag. This flag is set when the enter 
key is used to terminate a line of Input. The user Is responsible for 
clearing and checking this flag. It is set by EXPECT . 

ERASE addr\n 

Zero fills memory at addr for n bytes. If n is less than or equal to zero, 
take no action. 

ERA5E.RECT address - 

Erases contents of rectangle at address to background pattern, 
rectangle is 4 16 bit values representing top,left,bottom,right. 

ERROR addrXcnt -- 

Executes the cfa contained in the user variable (ERROR) . addr and cnt 
point to a string to be output. See (ERROR) , ((ERROR)) , (ERROR") , and 
ERROR" . 

ERROR" flag - 

Aborts the current task, displays the name of the word executed and 
the supplied message if flag is true. Used in the form: 

ERROR" <user error message>" 
Compiles (ERROR") followed by the inline literal string. If flag Is true 
when (ERROR") executes, the name field of the most recently 
Interpreted word (in POCKET ) is displayed, followed by the string <user 
error message), finally the system ABORTS, returning control to the 
console. If flag Is false, control is passed to the word following the 
string literal, "error-quote" 

EVENT.LOOP - 

Default loop which dispatches to the next active window. If all 
windows are deactivated, this word patiently executes do.events until 
an activate event occurs. 
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EVENT.RECORD -addr 

Array containing the event record for the current event. 

bytes: 0-1 contain the event code 

2-5 contain the event.message 

6-9 contain the mouse 

10-13 contain the time in ticks when the event occured 

M-15 contain the modifiers bits ( kbd state) 

EVENT.TABLE -addr 

Array containing default tokens to be executed for each of the 24 
standard events. DO.EVENTS always executes this token whenever the 
appropriate event occurs. The caller to do.events is also notified with 
an event code. 

EVENTS - addr 

Returns the address of the variable containing the mask for all events. 

EVENTS OFF 
Disables all events. No events are enabled when DO.EVENTS is called. 

EVENTS ON 
Enables all events. 

NOTE: If a keystroke is waiting in the keystroke array, the contents of 
EVENTS is anded with the constant -KEYBOARD , effectively disabling 
keyboard events until the keyboard data is read. This allows for type 
ahead. 

EXECUTE token - 

Execute the dictionary entry whose token is on the stack. 

EXIT 

Terminates execution of a definition. When compiled into a colon 
definition, causes the word to terminate at that point when later 
executed. An unchecked error exists if used within a DO .. LOOP 
structure or a >R ... R> pair. 

EXPECT addrXmax cnt — 

Accepts up to max cnt characters from the terminal and stores them at 
addr. Input terminates on receipt of either a carriage return or max 
cnt characters. No action is taken for max cnt less than one. The user 
variable CNT is set to the actual number of charaters recieved. 

EXTENDED - 64 

Constant bit mask for extended text attribute. 
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EXTERNAL - 2 

Constant drive number for the external drive. Use with EJECT , DIR 

FALSE - 

Boolean false constant. 

FCB.LEN *** Refer to the File System chapter glossary ** 

FENCE - addr 

Returns the address containing a pointer below which FORGETTING Is 
prevented, to FORGET below this point, alter the value in fence or use: 
FENCE OFF. NOTE: FENCE is set by the system to prevent FORGETting of 
interrupt handlers and vectored words so use caution when changing its 
value. See SET.FENCE, FORGET 

FIELD n - 

MacFORTH field defining word. Creates a 16 bit constant which will add 
itself to the word on the top of the stack when executed. 

FILE.ERR0RM5GS -addr 

String array containing file/os error messages. 

FILE.TYPE file.typeXfile* 

Sets the file type for the file (1e: "TEXT 1 FILE.TYPE). 

FILL addr\cnt\char — 

Fills memory at addr for cnt bytes with char. No action taken for cnt 
less than one. 

FIND ~ [token] or [0] 

Returns the token for the next word in the Input stream. If that word 
cannot be found In the dictionary after a search of CONTEXT or TRUNK 
vocabularies, returns a zero. 

FIND.CONTROL point\wptr ~ control.handleXcontrol part code 

Returns control part code and handle If point is In a control, part code: 
= no control 1 = in button 2 = in check box 3 = in up arrow 
4 = in down arrow 5 = in page up 6 = In page down 7 = in thumb 
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FIND.WINDOW point ~ wptrNwlndow part 

Returns window pointer under window part code. 
Part code: 

In desktop 

1 In menubar 

2 In system window 

3 In content of active window 

4 In drag of active window 

5 In grow of active window 

6 In close of active window 

FIRST - addr 

Returns the address of the first block buffer. 

FLUSH 

Writes all blocks that have been UPDATEd to mass storage. Identifies 
all blocks as 7FFFFFFF (hex) to force any new block to be re-read from 
mass storage. Use when changing media. 

FLUSH.EYENT5 - 

Flushes all pending events from 

FLUSH.FILE ** Refer to the File System chapter glossary ** 

FLU5H.Y0L ** Refer to the File System chapter glossary *^ 

FMT.DATES *days\flag ~ addrXcnt 

Formats a date string for output. The date formatted is in terms of 
*days since 01/01/84. If the flag is true the month, day and year are 
separated by slashed ("/"). The formatted string is placed at addr for 
cnt bytes. 

FMT.TIMES addr - 

Formats the time output string at addr in the following format: 
HH:m:SS XM 

FOLLOWER - addr 

User variable containing the address of the base of the user area for 
the following task in the multitasking round- robin task dispatch queue. 
With no other tasks running, this is the address of the console STATUS . 
See STATUS . 
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FORGET 

Removes entries from the dictionary. Used In the form: 

FORGET <name> 
to delete from the dictionary (In the CONTEXT vocabulary) all entries 
added after and including <name>. Forgotten Menus or windows are 
disabled. No action Is taken If <name> Is not found In the CONTEXT or 
TRUNK vocabularies. FORGETtIng Is terminated at the FENCE. 

FORTH 

The name of the primary vocabulary. When executed, FORTH becomes 
the CONTEXT vocabulary. 

FRAME - 

QuickDraw shape mode attribute. Shape will be drawn in outline mode. 

FROM.CURRENT - position mode 
See File System glossary. 

FROM.END — position mode 
See File System glossary. 

FROM.HEAP size - handle 

Requests memory manager to allocate a relocatable data structure in 
the heap of size bytes. Handle returned is non-zero if successful and 
contains the address of a pointer to the allocated data structure. The 
contents of the handle changes dynamically with the heap, however the 
address of the handle will never change. Refer to the Apple Developer's 
documentation for further details. Reference: NewHandle. See also: 
IN.HEAP, TO.HEAP, RESIZE.HANDLE 

FROM.START — position mode 
See File System glossary. 

FRONT.WINDOW - wptr 

Returns wptr to currently active (or front) window. 

FUNOL n - 

Macintosh toolbox Pascal function call compiler. Refer to the Advanced 
Topics Toolbox Interface section. 
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FUNOW n - 

Macintosh toolbox Pascal function call compiler. Refer to the Advanced 
Topics Toolbox Interface section. 

GET addr - 

Multitasking stub for source compatibility with future products. 

GET.CONTROL n--n 

Not supported In Level 1. Refer to MacFORTH Level 2 controls 
documentation. 

GET.CUR50R - 

Returns address of cursor In use. (0 Indicates default NW arrow). 

GETDATEI addr- 

Formats the current date Into a string In the format MM/DD/YY and 
places It at addr. 

GET.EOF ** Refer to the File System chapter glossary ^^ 

GET.FILE.INFO ** Refer to the File System chapter glossary ** 

GET.FILE.TYPE ** Refer to the File System chapter glossary ^* 

GET.ICON resid ~ handle 

Reads ICON RESID from the resource file. The handle to the ICON Is 
returned. See PLOT. I CON . 

GET.LINE.HEIGHT - line height 

Returns the line height for the current window. See the Graphics 
chapter. 

GET.PICTURE resid - handle 

Reads the picture RESID from the resource file, returning its handle. 

GET.PIXEL (x\y - flag) 

Returns TRUE If the pixel at X,Y in the current window is on. 

GET.REC.LEN ** Refer to File System chapter glossary ** 

GET.5CRAP *** Refer to the Advanced Topics chapter - Cutting and 
Pasting between Applications ** 
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GET.TEXTFONT -font* 

Returns text font number for current window. See graphics section. 

6ET.TEXTM0DE -mode 

Returns text mode for current window. See graphics section. 

GET.TEXT5IZE - text size 

Returns current text size. See graphics section. 

GET.TEXT5TYLE - style bits 

Returns text style bits for the current window. See graph- ics section. 

GET.TIMEI addr- 

Stores the formatted time string (in the format HH:MM:SS XM) at addr. 

GET.WINDOW - wptr 

Returns the window pointer of the currently active window. 

GET.XY0FF5ET ( - x\y ) 

Returns the offset in QuickDraw native coordinates to the 0,0 origin of 
the current window. 

GET.XYPIVOT - angle 

Returns current XYPIVOT angle for the current window. 

GET.XY5CALE ~ xscaleWscale 

Returns the X and Y scale factors for the current window. 

GINIT 

Initializes graphics parameters for the current window. The following 

defaults are set: 

XYPOS -> XYBIAS erased 

100 100 XYSCALE 

XYPIVOT 

12 TEXTS I ZE 

15 LINE.HEI6HT 

11 PENSIZE BLACK PENPAT 

XYOFFSET 

MOVE.TO 
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GLOBAL>LOCAL point - point 

Converts point In global coordinates to point In local coordinates 
relative to the currently active window. Point is two 16 bit words 
packed into 32 bits, y in high order word, x in lower. 

GRAY - addr 

Returns the address of the gray pattern. 

HANDLE.5IZE handle - size 

Returns size of relocatable data structure in heap. Reference 
APDEVDOC: GetHandleSize 

HANDLER - addr 

User variable containing the address of the Interrupt handler for the 
current task. 

HBAR.B0UND5 wptr - t\l\b\r 

Returns rectangle for horizontal scroll box within window. 

HERE - addr 

Returns the address pointed to by the dictionary pointer. It is the next 
available memory location in the dictionary. 

HEX 

Sets the current numeric I/O base to hexadecimal. 

HiDE.CURSOR - 

Increments cursor level. When cursor level is 0, cursor is visible. Use 
INIT.CUR30R to reset cursor level. See SHOW.CURSOR 

HIDE.PEN - - 

Decrements pen level in current graphport. See SHOW.PEN for 
discussion of why this may be useful. 

HIDE.WINDOW wptr - 

Clears visible flag in windwow at wptr. Window will immediately 
disappear from screen. 

HILITE.CONTROL n1\n2 - 

Refer to Level 2 Controls Documentation. 
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HILITE MENU n - 

Highlight menu n . Where n is 0, no menus are highlighted Normally used 
to turn off menu highlight which is auto- matically done when a menu 
item is selected. 

HILITE.WINDOW f lagXwptr - 

Window primitive. Hilights the specified window based on flag. 

HLD - addr 

User variable which holds the address of the latest character of text 
during numeric output conversion, "h-l-d" 

HOLD char - 

Inserts char into a pictured numeric output string. May only be used 
between <* and ^> . An unchecked error occurs when used outside <* 
and *> . See <* and *> . 

HUSH --- 

Immediately terminates any sound being produced by the sound driver. 

I -n 

Copies the loop index (maintained on the top of the return stack) onto 
the data stack. Must be used only within a DO ... LOOP structure. 
Unchecked error occurs if used outside a DO ... LOOP or DO ... +LOOP 
structure. Warning: If you use R> or >R inside a loop, the loop indices 
may be covered up. 

I! n - 

Stores n at the address corresponding to the current value of the loop 
Index. "1 -store" 

1+ n ~ n+(loop index) 

Increments the top of the stack by the current loop index. 



I+! nNoffset — 




Equivalent to 1 + 1. 




I+® offset ~ n 




Equivalent to 1 + @ . 




I+W! nXoffset ~ 




Equivalent to 1 + W!. 
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I+We» offset ~ n 

Equivalent to I + w@ . 

I- n — n-(1oop index) 

Decrements the top of the stack by the current loop index. 

I© --n 

Fetches n from the address corresponding to the current value of the 
loop index, "i-fetch" 

IBEAM - addr 

Returns address of I Beam cursor array. 

IC! char ~ 

Stores char (using C! ) at the address corresponding to the current value 
of the loop index, "i-c-store" 

IC© ~ char 

Fetches char (using C@ ) from the address corresponding to the current 
value of the loop index, "i-c-fetch" 

ID. nfa - 

Prints the name field of the definition whose nfa is given, "i-d-dot" 

IF flag-- 

Marks the beginning of the "true portion" of a conditional structure. 
Used in a colon definition in the form: 

IF ... THEN 
or 

IF ... ELSE ... THEN 
If flag is true, the words following IF until the ELSE (if present) or 
THEN (If ELSE is not present) are executed. If flag is false, control is 
passed to the words following ELSE (If present) or THEN (If ELSE Is not 
present). The error message DEFINITION INCOMPLETE ! indicates the IF 
was not matched with a THEN . See ELSE and THEN . 

IFEND 

Marks the end of an executable conditional structure. Executed In the 
form IFTRUE ... OTHERWISE ... IFEND or IFTRUE ... IFEND Execution 
version of the compiled IF ... ELSE ... THEN structure. This word is used 
as a marker for IFTRUE and OTHERWISE and if executed does nothing. 
See IFTRUE and OTHERWISE . "if-end" 
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IFTRUE nag- 

Marks the beginning of the "true portion" of an executable conditional 
structure. Executed In the form IFTRUE ... OTHERWISE ... IFEND or 
IFTRUE ... IFEND Execution version of the compiled IF ... ELSE ... THEN 
structure. IFTRUE performs the execution version of IF In the compiled 
version. If flag is true, the words following IFTRUE up to the 
OTHERWISE (If present) or IFEND (If OTHERWISE Is not present) are 
executed. If flag is false, control is passed to the words following 
OTHERWISE (If present) or IFEND (If OTHERWISE Is not present). The 
error message MISSING OTHERWISE OR IFEND Implies the input stream 
was exhausted before an OTHERWISE or IFEND was encountered. See 
IFEND and OTHERWISE . 

ILLEGALFILE — 

See File System glossary. 

IMMEDIATE — 

Marks the most recently defined word as "immediate". The word will be 
executed when encountered during compilation rather than compiled 
into the dictionary. 

IN.BUTTON -n 

Refer to Level 2 Controls Documentation. 

IN.CHECK.BOX -n 

Refer to Level 2 Controls Documentation. 

IN.CL05E.B0X -n 

Constant event code returned by DO.EVENTs when a mouse down occurs 
in the close box of the currently active window. 

IN.DE5KT0P - n 

Constant event code returned by DO.EVENTS when a mouse down occurs 
on the desktop. 

IN.DRAG.BOX - n 

Constant event code returned by DO.EVENTS when a mouse down occurs 
in the drag region of a window. 



MacFORTH Glossary Page 1 3 - 53 June 3, 1 984 



IN.HEAP 

Marks the latest word as containing a heap handle in Its parameter 
field. When the word Is later forgotten, the handle will be 
automatically returned to the heap. 

IN.LOWER.WINDOW -n 

Constant event code returned by DO.EVENTS when a mouse down occurs 
In a non.actlve window. 

IN.MENUBAR - n 

Constant event.code returned by DO.EVENTS when a mouse down occurs 
In the menu bar. 

IN.5IZE.B0X -n 

Constant event code returned by DO.EVENTS when a mouse down occurs 
In the size box of the currently active window. 

IN.5Y5.WIND0W - n 

Constant event code returned by DO.EVENTS when a mouse down event 
occurs In a system (desk accessory) window. 

IN.THUMB - n 

Refer to Level 2 Controls Documentation. 

INCLUDE- -- 

Refer to the File System chapter glossary. 

INDEX first screen*\last screen* ~ 

Displays the first line of each block over the range given. The first line 
of each screen should be a comment describing the contents of that 
screen. 

INIT.CUR50R - 

Resets cursor level to 0, displays northwest arrow (dfit) cursor. 

INITIALS - addr 

User variable containing the user's Initials for a terminal task. 
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INPUT.NUMBER width -- [n\true] or [false] 

Inputs a number of up to the width specified. If nothing is entered (the 
operator just pressed return), a false flag is returned. If a number is 
entered, the number is returned under a true flag. Invalid characters 
(non 0-9 or "-"), terminate number conversion when encountered. 

INPUT.STRING addrXcnt - 

Inputs a string to a string variable (or any address). After the string 
has been input, the number of characters entered is stored at addr, the 
string at addr+ 1 on. 

INTERNAL - 1 

Constant drive number for the internal drive, 

INTERPRET --- 

Executes 'INTERPRET . You may use an alternate text interpreter (for 
example, one that accepts floating point numbers) by storing the cfa of 
your new interpretation word into the pfa of INTERPRET . The actual 
definition of INTERPRET is simply: : INTERPRET 'INTERPRET ; *** 
Note: Be aware that modifying INTERPRET affects ALL tasks. 

INYALID.RECT addr - 

harks the rectangle at addr within the current window as not requiring 
updates. 

INVERT - 3 

QuickDraw shape mode attribute shape will be drawn with all bits 
inverted in the destination. 

I0-RE5ULT - addr 

See File System glossary. 

ITALIC - 02 

Constant bit mask for italic text attribute. 

ITEM.CHECK item\check.flag\menuid ~ 

Sets or clears check mark associated with item on menu menuid. 

ITEM.ENABLE item\f lagXmenuid -- 

Enables or disables item on menu menuid. Disabled items cannot be 
selected. 
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ITEM.ICON ItemXiconXmenu.id ~ 

Displays selected Icon with menu item. See menu section of 
documentation for further discussion of item icons. 

ITEM.MARK 1tem\mark\menuid ~ 

Selects mark to associate with menu item. See menu section in 
documentation for discussion of associated item marks i.e. check mark 

ITEM.5TYLE item\style.char\menuid 

Selects text style for menu item from style character. See menu 
section of documentation for description of style character. 

J --n 

Returns the index of the next outer finite loop construct. May used only 
within a nested DO .. LOOP (or DO .. +LOOP ). An unchecked error occurs 
if used outside a DO ... LOOP or DO ... +LOOP structure. 

KEY -- char 

Returns the ASCII value of the next available character from the 
current input device. 

KEY.DOWN - n 

Constant event code returned by DO.EVENTS on a key down event. 

KEYSTROKE - addr 

Array containing the event record for the most recent keystroke. A two 
byte filler is added to the front of the record so that the first four 
bytes may be used as a flag. ie. KEY.STROKE @ See EVENT.RECORD for 
field layout 

KEY.UP - n 

Constant event code returned by DO.EVENTS on a key up event 

KILL.CONTROLS wptr- 

Refer to Level 2 Controls Documentation. 

KILLIO bufptr- 

Aborts any pending i/o transaction on device associated with buf.ptr. 

L>FUNC>L n - 

Macintosh toolbox function call compiler. Refer to the Advanced Topics 
chapter, toolbox interface discussion. 
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LATEST - nf a 

Returns the nfa of the most recently defined word in the CURRENT 
vocabulary. 

LEAVE 

Forces termination of a finite loop structure at the next LOOP or +LOOP. 
Sets the loop limit equal to the current value of the index. The index 
itself remains unchanged and execution proceeds normally until the 
loop terminating word ( LOOP or +LOOP ) is encountered. An unchecked 
error occurs if used outside of a DO ... LOOP or DO ... +LOOP with 
unpredictable results. 

LIMIT - addr 

Returns the address just above the highest memory available for a disc 
buffer. This is usually the highest system memory. 

LINE* - addr 

User variable containing the number of lines output. This variable is 
incremented by CR and set to zero by PAGE . 

LINE.HEIGHT n- 

Sets line height to n scaled by Y scale. 

LIST block* — 

Lists the contents of the given block number. The value in OFFSET is 
taken into account. See OFFSET . 

LIT -n 

Places the compiled number following it on the stack. Within a colon 
definition, LIT is automatically compiled before each literal number 
encountered in the input stream. Later execution of LIT causes that 
number to be placed on the stack, if LIT is compiled, the following 
32-bit value (usually a compiled cfa) will be pushed on the data stack 
at run time. 

LITERAL n - 

If compiling, compile n as a literal number, which when later executed 
operator takes the number off of the data stack at compile time. For 
example, to compile the number of the current block, you could execute 
the following [ BLK @ ] LITERAL This would return the block number 
that the definition was compiled into at run time. 
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LMO VE addr 1 \acldr2\cnt - 

Moves cnt 32 bit words from address 1 to address2. 

LMOVE> src addrXdest addrXcnt ~ 

Moves cnt long words (32-bit, 4 byte) from src addr to dest addr. Starts 
at the end of the array and proceeds towards low memory, "move-up" 

LOAD block* ~ 

Interprets the contents of block*. Begins Interpretation of the block 
number given by making It the Input stream and preserving the current 
contents of >IN and BLK . If Interpretation Is not terminated explic- 
itly, It will be terminated when the Input stream Is exhausted. Control 
then returns to the Input stream containing LOAD , determined by the 
input stream locators >IN and BLK . The value In the user variable 
OFFSET is added to the block* given. Error if the specified block cannot 
be loaded from mass storage. See BLOCK , >IN , BLK , and OFFSET . 

L0AD.5CRAP - io result 

Loads the clipboard Into memory. 

LOCAUGLOBAL point - point 

Converts point in coordinates local to the currently active window to 
global screen coordinates. Point is two packed 16 bit words, y in higher 
word, X In lower. 

LOCK.FILE ** Refer to the File System chapter glossary ** 

LOCK.FONT font* - 

Locks font in memory. Will not be lost on heap compression. 

LOCK.HANDLE handle - 

Marks relocatable heap data structure as locked. See Apple Developer's 
documentation for further details. Reference: HLock 

LOOP 

Terminates a finite loop structure. Used in the form: 

DO ... LOOP 
Increments the DO ... LOOP index by one, terminating the loop If the new 
index is equal to or greater than the loop limit. The error message 
CONDITIONALS NOT PAIRED Indicates the LOOP was not preceded by a 
matching DO . See DO and +LOOP . 
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L0WER.CA5E - addr 

User variable containing a flag which when true causes FIND to convert 
all Interpreted strings to upper case. LOWERCASE ON Enables 
conversion L0WER.CA5E OFF Disables conversion 

LOWER.LEFT --- 

Sets the graphics XYOFFSET to the lower left corner of the current 
window. 

LTGRAY - addr 

Returns the address of the light gray pen pattern. 

M* n1\n2--d 

Returns the signed 64-b1t product of the two signed 32-bit numbers 
given, "m-star" 

M/MOD d\n ~ remainder\quotient 

Divides the 64-bit number d by the 32-bit number n, return- ing the 
32-bit signed remainder and quotient, "m-dlvide-mod" 

MAC.CON - addr 

Array containing console device i/o vectors for Macintosh console. 

MAC.C0N50LE ~ 

Sets Macintosh console as default console device. 

MAC.FILE5 - 

Sets the file read/write operator for blocl<s to MAC.R/W. See MAC.R/W, 
(R/W) 

MAC.R/W addr\block*\flag ~ 

Standard Macintosh block file read/write primitive. If flag is non-zero. 
Block is read to address. If flag is zero, block Is written from address. 

MAKE.RECT x 1 \y l \x2\y2 ~ xy\xy\ addr 

Compresses XY coordinate pairs into a TLBR rectangle. The address of 
the rectangle within the stack is left on the stack. 
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MAKE.TOKEN addr - token 

Converts the address on the stack to a 16 bit token. If the address is 
greater than NEXT.PTR+32k, a new entry is made in the token table, and 
the relative offset to the token table entry (below NEXT.PTR) Is 
returned. All tokens are 16 bit values, Token table offsets are negative 
from NEXT.PTR. See NEXT.PTR, NEW.TOKEN, TOKEN> ADDRESS. 



MATCH $\$ cnt\addr\cnt - [0\addr2] or [true\addr3] 

String comparison routine to find a match on the string at $ (its 
address) for $ cnt bytes over the range addr for cnt bytes. 

MAX nl\n2--n3 

Leaves the maximum of n1 and n2. "max" 

MAX.X - X 

Returns the maximum X coordinate in QuickDraw native representation 
of the content region of the current window. 

MAX.Y - y 

Returns the maximum Y coordinate in QuickDraw native representation 
of the current window. 

MENU.ENABLE flag\menuid - 

If menu is non-zero, menu is enabled, otherwise menu is disabled, and 
cannot be selected. 

MENU.HANDLE menuid ~ menu.handle 
Returns handle for menu menuid. 

MENU.SELECTION: menuid - 

Exits the current definition, placing the following address into the 
menus array at menuid*4. When the menu is later executed, control is 
passed to the following address. See Menu section of the documentation 
for further details. 

MENUS - addr 

16 element array containing the address to execute for each of the 16 
possible active menus. 

MIN n1\n2-n3 

Leaves the minimum of n1 and n2. "min" 
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MINIMUM.OBJECT size- 

If the current object size is less than the specified size, MacFORTH 
attempts to resize the object image to the specified size. See 
RESIZE.OBJECT 

MINIMUM. VOCAB size - 

If the current vocabulary size is less than the specified size, MacFORTH 
attempts to resize the vocabulary image to the specified size. See 
RESIZE. VOCAB 

MOD n1\n2--n3 

Returns the remainder of n1 divided by n2, with the same sign as nl. 
Error if division by zero (see */ ). "mod" 

MONTHS -addr 

Returns the address of the table containing the number of days in each 
month. 

M0U5E.BUTT0N -flag 

Returns state of mouse button. True when down. 

MOUSEDOWN - n 

Constant event code returned by DO.E VENTS if a mouse down event 
occurs, ie. MOUSE.DOWN @ See EVENT.RECORD for field layout 

MOUSE.DOWN.RECORD - addr 

Array containing the event record for the most recent mouse down 
event. A two byte filler is added to the record so that the first four 
bytes may be used as a flag. i.e. MOUSE.DOWN.RECORD @ See 
EVENT.RECORD for format, (add 2 bytes at start) 

MOUSEUP - n 

Constant event code returned by do.events if a mouse up event occurs, a 
flag. ie. MOUSE.UP @ See EVENT.RECORD for field layout 

MOUSE.UP.RECORD -addr 

Array containing the event record for the most recent mouse up event, a 
two byte filler has been added to the start of the record so that the 
first 4 bytes may be used as a flag. ie. MOUSE.UP.RECORD @ See 
EVENT.RECORD for format ( add 2 bytes at start) 
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M0U5E.WA5.. -point 

Returns location of where the mouse last went down In global 
coordinates. 

MOVE.TO x\y - 

Moves the pen to the supplied X,Y position. 

MT n - 

Macintosh toolbox procedure call compiler. Refer to the Advanced 
Topics chapter toolbox interface discussion. 

MT>W n - 

Macintosh toolbox procedure call compiler. Refer to the Advanced 
Topics chapter toolbox interface discussion. 

MUNGER handle\offset\addrl\cnt1\addr2\cnt2 - result 
Macintosh universal string operator. 

NEEDED ( n - ) 

Aborts the current definition if less than n items are available on the 
stack. 

NEGATE n - -n 

Returns the two's complement of n. Error if n is the most negative 
integer, system response is to return the same value given. 



NETWORK.EVENT - n 

Constant event code returned by DO.EVENTS on a network event. 

NEW.MENU pos1tion\title$\menu1d ~ 

Defines new menu, links It Into menu list, menuld must be in the range 
0-15, titles is preceeded by the count, and position of places item on 
the left, -1 on the right See menu section of documentation for 
examples . 

NEW.5TRING str.addr ~ handle 

Allocates new handle from heap for string and copies string into 
handle. Handle is returned on stack. Use IN.HEAP to tag any word 
defined with this handle in order to deallocate handle when word is 
forgotten. 
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NEW.TOKEN addr - token 

Converts address on stack to an indirect token. An entry Is made in the 
token table, and the negative relative address to NEXT.PTR of the token 
table entry is returned. Used by NEW.TOKEN to handle addresses > 
NEXT.PTR+32k. 

NEW.WINDOW 

MacFORTH window defining word. Creates named window record which 
will return it's wptr when executed. 

NEXT.FCB -file* 

Returns the file number for the next available file control block for 
assignment. Aborts with the error message "No FCBs Available!" if all 
FCBs are in use. 

NEXT.PTR - addr 

Returns the address contained in the relocation base register, A4 
Positive tokens are merely added to A4 to provide the actual address. 
Negative tokens are added to A4 to produce an address within the token 
table. The 32 bit address contained at this location in the token table is 
then added to A4 to produce the actual address. Assembly code for the 
fundamental FORTH primitive NEXT starts at NEXT.PTR. 

NFA pfa ~ nfa 

Converts the pfa given to the nfa for the definition, "n-f-a" 

NO.CLIP wptr - 

Disables clipping within window bounds. Note that controls may only 
be drawn or updated if CLIP>CONTENT is active. 

NO.ECHO - addr 

User Variable containing a flag which is used by EXPECT. When NO.ECHO 
is non-zero, EXPECT does not echo keystrokes, to the console. QUIT 
resets this flag to the default cleared (or always flag true to disable 
echo when it calls EXPECT. Uses include: passwords,and fully 
intrepreted text fields ( ie: left zero fill calculator type text entry ) 
NO.ECHO ON disabled keystroke echo NO.ECHO OFF echoes keystrokes 
in EXPECT 

NO.RETRY — 

Procedure which pops the recovery stack frame from the return stack. 
Pushed onto the return stack at the bottom of the recovery frame. 
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NON.PURGABLE handle - 

Marks relocatable heap data structure as non-purgeable. See Apple 
Developer's documentation for further details. Reference: HNoPurge 

NOT flag — -flag 

Reverse the boolean value of the flag given. This is identical to 0= . 
See 0= . 

N0T.VI5IBLE -n 

Constant bit mask for not.visible v^indow attribute. 

NOTPATBIC - n 

Constant specifying bit transfer mode. Current pattern is 
complemented and used to clear corresponding bits in the destination. 

NOTPATCOPY - n 

Constant specifying bit transfer mode. Current pattern is 
complemented and copied directly into destination. 

NOTPATOR - n 

Constant specifying bit transfer mode. Current pattern is 
complemented and Or'ed into destination. 

NOTPATXOR - n 

Constant specifying bit transfer mode. Current pattern is 
complemented and Exclusive Or'ed into the destination. 

NOTSRCOR - n 

Constant specifying bit transfer mode. Source pattern is complemented 
and Or'ed with destination. 

N0T5RCBIC - n 

Constant specifying bt transfer mode. Source pattern is complemented 
and used to clear corresponding bits in the destination. 

NOTSRCCOPY - n 

Constant specifying bit transfer mode. Source pattern is complemented 
and copied directly to destination. 

N0T5RCX0R - n 

Constant specifying bit transfer mode. Source pattern is is 
complemented and Exclusive Or'ed with destination. 
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NULL.EVENT - n 

Constant event code. No events posted. 

NUMBER addr - n 

Attempts to convert the string at addr+ 1 to a number. If successful, n 
is returned, otherwise an error is generated indicating that the string 
was not recognized as a number in the current base. 

OBJECT.FULLI! - - 

Aborts with the error message "Object Full!" if the object area is full. 

OBJECT.HANDLE -addr 

User variable which contains the address of the handle which points to 
the base of the current object area. The object area Is allocated from 
the heap and is set up as locked and nonpurgable. This area may be 
resized with the RE51ZE.0BJECT operator as long as no other 
non-relocatable memory allocation has occured above this address. 

OBJECT.ROOM ~* bytes 

Returns number of bytes available in the current object space. 

OF n1\n2~[n1]or[] 

Marks the beginning of a conditional branch within a case statement. 
Used in the form: 
CASE ... 

X OF ... ENDOF 
ENDCA5E 
If n1 Is equal to n2, both arguments are dropped, and execution 
continues through ENDOF and then skips to the next ENDCA3E . If nl is 
not equal to n2, n2 is dropped and execution continues after ENDOF . 

OFF addr ~ 

Stores a 32-bit zero at addr. 

OFF.CONTROL n - 

Refer to Level 2 Controls Documentation. 

OFFSET - addr 

User variable containing the block offset value. Used by BLOCK to 
determine the actual physical block number to be accessed. 

ON addr ~ 

Stores a 32-b1t -1 at addr. 
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ON.ERROR - 

Establishes the recovery stack frame. Compiles (ON.ERROR) to 
establish this frame and branches over the recovery code past the 
delimiting RESUME. Used in the form: 
ON.ERROR <recovery code> RESUME 

ON.ACTIVATE wptr- 

Defines token to execute when window is activated. Used in the form: 

<wptr> ON.ACTIVATE <procedure> 
When <procedure> is later invoked (as a result of the window becoming 
active) a flag is left on the stack, if the flag is true, it is an activate 
event, if false, it is a deactivate event. 

ON.CONTROL n- 

Refer to Level 2 Controls Documentation. 

ON.UPDATE wptr- 

Deflnes the token to be executed when an update event occurs for 
window wptr. Used In the form: my.wlndow on.update 

redlsplay.window When an update event occurs, redisplay. window will 
be executed with my.wlndow temporarily set as the graphport. 

OPEN file* - 

Refer to the File System glossary. 

OPEN.DEVICE name$\fcb - 

Attempts to open the device named name$ with fcb. Aborts on error. 

OPEN.PORT wptr - 

Initializes the graphport at wptr. 

OPEN.PRINTER --- 

Opens the printer device driver. 

0PEN.50UND - 

Opens the sound device driver. 

OPEN.RSRC file*- 

See File System glossary. 

OPTIONS-MENU — 

Installs the MacFORTH options menu on the Menu Bar. 
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OR nl\n2--n3 

Leave n3 as the bitwise Incluslve-OR of two numbers. 

OS.TRAP n - 

Macintosh operating system trap call compiler. Refer to the Advanced 
Topics chapter toolbox interface discussion. 

OTHERWISE — 

Marks the beginning of the "false portion" of an executable conditional 
structure. Used in the form IFTRUE ... OTHERWISE ... IFEND Equivalent 
in control flow to ELSE in the compiled IF ... ELSE ... THEN construct. 
See ELSE . 

OUTLINE - 08 

Constant bit mask for outline text attribute. 

OVAL X 1 \y 1 \x2\y2\{patternl\mode — 

Draws oval within rectangle xl y1 x2 y2 according to mode. [PATTERN] 
present for pattern mode. 

OVER n1\n2--n1\n2\nl 

Copy the second stack item over to the top of the stack. 

PAD - addr 

Returns the address of a scratchpad area. Used to hold character 
strings for intermediate processing, as well as a scratchpad area for 
other tasks. The minimum capacity of PAD is 64 characters. 

PAGE 

Outputs a form feed to the current display devices. This clears the 
console display and ejects a page on any attach- ed printers. 

PAGEDOWN - n 

Refer to Level 2 controls documentation. 

PAGEUP - n 

Refer to Level 2 controls documentation. 

PAINT - 1 

QuickDraw shape mode attribute shape will be drawn filled with pen 
pattern. 
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PATBIC - n 

Constant specifying bit transfer mode. Current pattern is used to clear 
corresponding bits in destination. 

PATCOPY - n 

Constant specifying bit transfer mode. Current pattern is directly 
copied into destination. 

PATOR - n 

Constant specifying bit transfer mode. Currrent pattern is OR'ed into 
destination. 

PATTERN pattern — pattern\4 

Quicl<Draw shape mode attribute shape will be filed with supplied 
pattern. 

PATXOR - n 

Constant specifying bit transfer mode. Current pattern is exclusive 
OR'ed into destination. 

PAUSE 

Stub for source compatability with later products. 

PEN.NORMAL - 

Resets state of pen in current graphport: pensize = 1,1 penmode = 
patcopy penpat = black 

PENMODE n - 

Sets pen transfer mode. Allowable modes include: PATCOPY PATXOR 
NOTPATCOPY NOTPATXOR PATOR PATBIC NOTPATOR NOTPATBIC See 
individual modes for definition of function. 

PENPAT addr - 

Sets the pen pattern for current graph port. 

PENSIZE widthXheight ~ 

Sets pen size to width and height scaled by XYSCALE. 

PFA token ~ pfa 

Convert the token of a compiled definition to its pfa. "p-f-a" 
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PICK nl -n2 

Return the stack Item nl Items from the top (not including nl). For 
example, 2 PICK Is functionally equivalent to OVER ; 1 PICK is 
functionally equivalent to DUP . An error condition exists for nl less 
than 1 , system response is to leave nl on the stack. 

PLAIN -n 

Constant for no text enhancements. 

PLAY addr - 

Passes addr+2 to the Macintosh sound generator. Addr contains 16-bit 
length of the waveform description record at addr+2 on. System will 
hang until the sound is completed. 

PLOT.ICON rect\handle - 

Plots Icon at handle within supplied rectangle. 

PNTR - addr 

User variable containing the address to which characters are 
transferred, "p-n-t-r" 

POCKET - addr 

User area array used for parsing text strings from the input stream. 
WORD uses this 256 byte area when extracting strings from the input 
stream. If the task does not compile text, this area may be user 
defined for further user variables. 

POINT position mode\posltion\flle* — 

See File System glossary. 

POINT>XY point - x\y 

Unpacks point into x under y. 

POLYGON handle - 

Refer to Level 2 advanced graphics documentation. 

P05ITI0N.FIXED 

** Refer to the File System chapter glossary ** 
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P05T.EYENT event.codeXevent.msg ~ 

Places event of type event.code into event queue with message of 
event.msg. BE CAREFUL not to post events for such things as activate or 
update events as these are sure to crash the system. Normally posted 
events should be limited to user designated range 12-15. 

PREV - addr 

Returns the address of the variable which points to the disc buffer 
most recently referenced. The UPDATE command marks this buffer as 
changed so it is later written to disc when needed. 

PRINT addr\cnt ~ 

Sends the string of characters starting addr for cnt bytes to the 
printer. 

PRINT.BIT5 t\l\b\r\bit map -- 

Prints the pixels within the top, left, bottom, right rectangle of bitmap 
to an Apple Imagewrlter printer, bitmap Is wptr+2. 

PRINT.FCB -addr 

Returns the address of the printer device driver FCB. 

PRINT.5CREEN — 

Prints the contents of the screen to the Apple Imagewrlter printer. 

PRINT.WINDOW — 

Prints the contents of the currently active window to the Apple 
Imagewrlter printer. 

PRINTER - addr 

Returns address of printer resource variable. In single user systems, 
this variable is used to turn on and off duplicating screen output to the 
printer. PRINTER ON turns on printer PRINTER OFF turns off printer 

PRINTER.ONLY -addr 

Returns the address of the device console table which directs output to 
the printer. 

PTINRECT point\rect.addr - flag 

Returns true if point is within rectangle. 
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PURGABLE handle - 

Marks handle as purgable by memory manager. 

PUSHBUTTON n1\n2\n3\n4\n5-- 

Refer to Level 2 controls documentation. 

PUT.5CRAP addr\cnt\res type ~ io result 

Writes cnt bytes from addr to the desk scrap and marks it with res 
type. 

QUERY 

Accepts input of up to 80 characters from the keyboard. A carriage 
return will stop input when encountered. The string is stored in the 
terminal input buffer. Two nulls are appended to the input stream and 
CNT contains the actual number of characters input. A space is output 
when a CR is entered. WORD may be used to accept text from this 
buffer as the input stream by setting >IN and BLK to zero. See TIB , 
WORD, >IN. and BLK. 

QUIET - addr 

User variable mode switch. When non.zero, indicates the buzzer Is not 
to sound when a user-defined error condition is encountered (ie. using 
ERROR" ). QUIET ON Enables Quiet mode. QUIET OFF Disables Quiet 
mode. 

QUIT 

Stops execution of the current task, clears the return stack and returns 
control to the terminal. No message is given and the data stack is 
preserved. 

R* ~ addr 

User variable which contains block offset to location of latest ERROR. 

R/W addr\block\f lag — 

The mass storage read/write primitive, addr specifies the source or 
destination block buffer, block Is the number of the referenced block, 
and flag determines the operation to take place (0 Implies write, 1 
Implies read). Execution Is vectored through the User Variable (R/W) to 
the user spec- if led read/write handler. 

RO ~ addr 

User variable containing the Initial location of the return stack. See 
RP! . "r-zero" 
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R> -n 

Pops the top item off of the return stack and pushes it onto the data 
stack. MUST be matched with a >R within the same colon definition or 
an unpredictable error will occur. T-to" See >R. 

R>DROP 

Code routine which drops the top item from the return stack, 
"r-from-drop" 

R» -n 

Copies the top of the return stack to the data stack. Should only be used 
between a >R ... R> sequence, "r-fetch" 

RANGE n\min\max ~ n\bool 

Performs a range check for min <= n <= max. Bool is the boolean result 
(true if min <= n <= max). 

RADIO.BUTTON n1\n2\n3\n4\n5-- 

Refer to Level 2 controls documentation. 

RANDOM -n 

Returns a psuedo random number between and 32767. See SEED 

RANGE.OF n 1 \min\max -- [n I ] or [] 

Marks the beginning of a conditional branch within a case statement. 
Used in the form: 
CASE ... 

<min> <max> RANGE.OF ... ENDOF 
ENDCASE 
If n1 is <= max and >= min, all arguments are DROPped and execution 
continues through ENDOF and then skips to the next ENDCASE . If n1 is 
not with min and max, min and max are DROPped and execution 
continues after ENDOF . See OF , ENDOF , CASE , and ENDCASE . 

RDRAW dx\dy - 

Relative draw. Draws from current XY position to XY position at x + dx, 
y + dy dots to the right of and below the pen are modified according to 
the pen size, shape, pattern and mode. 

READ.FIXEO addr\rec*\file* -- 
See File System glossary. 
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READ.TEXT acldr\cnt\file* -- 
See File System glossary. 

READ.VIRTUAL addrXcntXfile addrXfile* -- 
See File System glossary. 

REALFONT? font*\size -- flag 

Returns true if font is an actual rather than synthesized font. 

RECOVER 

Recovery routine for errors In the floppy boot RON handler. 

RECOVER.HANDLE ptr - handle 

Returns handle for address if address corresponds with a valid 
relocatable data structure in the heap. Reference APPDEVDOC: 
RecoverHandle 

RECT t\l\b\r -- 

Creates rectangle data structure which will place it's address on the 
stack when executed (like variable ). 

RECTANGLE x 1 \y 1 \x2\y2\[pattern addr]\mode -- 
Rectangle according to mode. 

REG.SET - addr 

Returns the address of a register snapshot array. Contains a snapshot 
of the 68000 registers and the last 16 bytes of the parameter and 
return stacks when the last exception occurred. See (EXCPT) . 

REGION 

Refer to Level 2 advanced graphics documentation. 

RELEASE addr- 

Multitasking primitive which releases a resource. If addr, a resource 
variable, contains the current task's status address, the resource 
variable is RELEASEd (set to zero), otherwise no action is taken. 

REMOVE flle*-- 

Refer to the File System chapter glossary. 

RENAME file$\f11e* -- 

Renames the specified file (by number) with the specified name. 
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REPEAT 

Terminates a finite control structure. Used within a colon definition in 
the form: 

BEGIN . . . WHILE . . . REPEAT 
Returns control to the word following the corresponding BEGIN . The 
error message CONDITIONALS NOT PAIRED indicates the structure Is 
missing either a BEGIN or WHILE command. 

RESIZE.HANDLE handle\s1ze - flag 

Attempts to resize handle in heap. Returns non-zero if unsuccessful. 
Reference APDEVDOC: realloc.handle 

RE5IZE.0BJECT size - 

Attempts to resize the current object space. An error message results 
if insufficient heap space exists or if the requested size is unable to 
contain the current object image. Use the ROOM function to determine 
the current object space allocation. 

RE5IZE.Y0CAB size - 

Attempts to resize the current vocabulary to the requested size. An 
error message is generated if insufficient heap space Is available or If 
the vocabulary is currently larger than the requested size. 

RESUME - 

Terminates a user specified error handler. See ON.ERROR 

RETRY - addr 

User variable pointing to the most recently specified error recovery 
frame. See ABORT" . RECOVER , ON.ABORT . 

REWIND file* - 

See File System glossary. 

RMOVE dx\dy - 

Relative move. Moves the current pen position to current position plus 
the supplied offset. 

ROLL n1 -n2 

Extracts the stack Item n1 from the top (not including nl). The 
remaining stack items are moved into the vacated position. For 
example, 3 ROLL is equivalent to ROT 2 ROLL is equivalent to 
SWAP Error if nl is less than or equal to one with no action taken. 
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ROOM 

Displays the amount of remaining memory available for use. The 
message displayed is xxxxxxxx Object Bytes Available yyyyyyyy 
Current Vocabulary Bytes Available zzzzzzzz Heap Bytes Available 
Where xxxxxxxx represents current object area ( pointed to by 
OBJECT.HANDLE), yyyyyyyy represents the amount of space in the 
CURRENT vocabulary (pointed to by CURRENT) and zzzzzzzz represents 
the total amount of space remaining in the HEAP. 

ROT n 1 \n2\n3 — n2\n3\n 1 ^ 

Rotates the top three staclc items. The third item is brought to the top. 
"rote" 

RP! 

Initializes the return stack to point to the value contain- ed in the user 
variable RO . "r-p-store" 

RP@ - addr 

Returns the address of the top of the return stack. 

RRECT ANGLE x 1 \y 1 \x2\y2\ch\cw\[pattern]\mode - 

Drav^s rounded rectangle with ch by ch radius rounding [pattern] 
present for pattern mode. 

RSRVMEM size - iorslt 

Requests memory manager to reserve size bytes in heap for a upcoming 
relatively static or locked data structure. See Apple's Developer's 
documentation for further details. Reference: ResrvMem 

R5T.PRINTER -- 

Resets the Apple Imagewrlter printer by sending an esc c sequence. 

SO — addr 

User Variable containing the address of the top of the stack when it is 
empty, "s-zero" 

5AYE-BUFFERS - - 

Writes all UPDATEd blocks to disc. The contents of the block buffers 
remain unchanged and available. See BLOCK , UPDATE , and FLUSH . 
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SCALE n1\n2--n3 

Arithmetically shifts nl according to the value of n2. If n2 is negative, 
n1 is shifted right, if n2 is positive, nl is shifted left. The absolute 
value of n2 determines the actual shift. For example; : NEW.2* ( n — 
n**2 ) I SCALE ; is equivalent to 2* . Error if n2 is greater than 31, 
system responds by leaving n3 as zero. 

5CALE>XY XI Wl -X2\y2 

X2 = x1 * 100/XSCALEY2 = yl * 100/YSCALE 

5CALE>Y n-- n* 100\YSCALE 
N is scaled to Y. 

5CAN.FR0M - addr 

Computes the address within the input stream of the next word, addr is 
either TIB + >IN or BLK + >IN if BLK is non- zero. See BLK , TIB , and >IN . 

SCR ~ addr 

User variable containing the number of the screen most recently LISTed 
or EDITed. "s-c-r" 

SCRAP.COUNTER - n 

Returns the number of times the desk scrap has been zeroed. 

SCRAP.HANDLE -addr 

Returns the address containing the desk scrap handle. 

SCRAPIEN -addr 

Returns the address containing the length of the desk scrap. 

SCRATCH - addr 

User variable used to hold the most recently referenced option bit 
switch. All switch references set the appropriate bit at this location. 

5CREEN.BITS -addr 

Returns the address of the rectangle which contains the maximum 
screen coordinates. 

SCROLL - 

Scrolls the current window up the number of pixels contained in the 
current line height of the window. See 6ET.LINE.HEIGHT LINE.HEIGHT 
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SEED -addr 

Returns the address of the random number generator seed. 

SELECT file^-- 

Refer to the File System glossary. 

5CR0LLLEFT/RIGHT -n 

Constant bit mask for horizontal scroll control window attribute. 

SCROLL.UP/DOWN -n 

Constant bit mask for vertical attribute. 

SELECT.WINDOW wptr - 

Causes wptr to be activated as currently active window. 

SEND.BEHIND wptrXbehind wptr ~ 

Re-links the window specified by wptr behind the window specified by 
behind wptr. 

SET.CONTROL n1\n2-- 

Refer to Level 2 controls documentation. 

SET.CONTROLM AX n 1 \n2 - 

Refer to Level 2 controls documentation. 

SET.CONTROL MIN nl\n2 - 

Refer to Level 2 controls documentation. 

SET.CONTROLRANGE n1\n2\n3 - 

Refer to Level 2 controls documentation. 

5ET.CUR50R cursor address — 

Sets cursor to supplied address. ( indicates default NW arrow). 

5ET.E0F 

Refer to the File System chapter glossary. 

5ET.FENCE - 

Sets the FENCE to point to the current dictionary offset within the 
relocatable vocabulary structure. FENCE is stored at CURRENT @@ 8+ . 
The current vocabulary offset pointer is stored at CURRENT @@ 
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5ET.FILE.INF0 file* - 

Refer to the File System glossary. 

SET.ITEMS 1tem\1tenn$\menuici ~ 

Replaces current menu item string with supplied string. 

SET.ORIGIN X\Y - 

Establishes window origin in QuickDraw native screen coordinates. 

5ET.REC.LEN rec lenXfile* -- 

See File System Glossary (in File System chapter). 

5ET.5TRING handleXstring.addr -- 

Places string into handle. Prior handle contents are lost. 

5ET.WTITLE str.addr\wptr ~ 

Sets window title to supplied string. If window is visible title will be 
updated on the screen. 

5ETUP.5ERIAL * stop bits\parity\* data bitsXbaud rate\FCB addr - 
Sets up the serial Interface. Refer to the Printer/Serial Interface 
chapter. 

SHADOW - 16 

Constant bit mask for shadow text attribute. 

SHOW starting screen*\ending screen* ~ 

Generate a listing of TRIADS between the starting and end- ing screen 
numbers given. See TRIAD . 

SH0W.C0NTR0L5 wptr - 

Displays controls for window. 

SHOW.CURSOR - 

Decrements cursor level. When cursor level is 0, cursor is visible. Use 
INIT.CURSOR to reset cursor level to 0. See HIDE.CURSOR 

5H0W.PEN - 

Increments pen level in current graphport. When pen level is 0, drawing 
functions are displayed on the screen. This is used when defining 
regions, or pictures where the pen is used to depict a region or picture 
without actually drawing the outline on the screen. 
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SHOW-WINDOW wptr - 

Sets visible flag In window at wptr. Visible portions of window will 
appear on display. 

SIGN n - 

Insert the ASCII negative sign Into the pictured numeric output string 
If n is negative. *** Note: You must retain the sign of the original value 
being converted and place it on the stack before executing SIGN . Error 
if used outside of <* and *> pair with no system response. See <* and 
*> . 

SIN angle --SINE* 10000 

Returns Integer sine of angle * 1 0000. ( 4 digit precision). 

SIZE.BOX - n 

Constant bit mask for size.box window attribute. 

5IZE.WIND0W wptr - 

Recalculates window content, region, allocating space for only desired 
scroll bars. 

SMUDGE 

Used during word definition to toggle the "smudge bit" in a definition's 
name field. This prevents the incomplete definition from being found 
during dictionary searches, until compilation is completed without 
error. 

SOUND.FCB -addr 

Returns the address of the sound driver FCB. 

SP! 

Procedure to initialize the stack pointer to SO . See SO . "s-p-store" 

SP® ~ addr 

Returns the address of the top of the stack just before SP@ was 
executed, "s-p-fetch" 

SPACE 

Displays an ASCII space on the current output device. 
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SPACES n - 

Outputs n spaces to the current output device. No action is taken for n 
less than one. 

SORT ( n ~ square root ) 

Computes a 16 bit square root from 32 bit square n. 

SRCBIC - 3 

QuickDraw bit transfer mode. Bits set in the source pattern are cleared 
in the destination. 

5RCC0PY - 4 

QuickDraw pattern transfer mode. All bits set in the source pattern are 
copied to the destination. 

5RC0R - 4 

QuickDraw pattern transfer mode. Bits set in the source pattern are 
set in the destination. 

5RCX0R - 3 

QuickDraw bit transfer mode. Bits set in the source pattern are 
inverted In the destination. 

5TACK.ERR0R (flag -) 

Aborts with " not enough stack Items" error message if flag is true. 

START.FLAG -n 

Constant used by MacFORTH to determine if the system has been booted. 

STATE - addr 

User variable containing the compilation state. A non-zero value 
indicates compilation mode, zero indicates execution. 

STATUS - addr 

Returns the base address of the current task's user area. 

STILL.DOWN - flag 

Returns true while mouse is still down. If mouse comes up and goes 
down between samples, returns false. 

STRING.WIDTH addr-n 

Returns the width, In pixels of the string at addr. 
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SWAP n1\n2--n2\n1 

Swaps the top two stack items. 

5Y5.FILE -addr 

FCB address used for system related file functions. 

SY5.WIND0W - wptr 

Default interactive MacFORTH Window. 

5Y5BEEP duration -- 

Sounds the buzzer for the number of specified 1/60 sec ticks. 

5Y5PARM5 -addr 

Returns the low memory address of data copied from battery backed-up 
memory. 

5Y5TEM.EDIT n - f 

Allows desk manager an opportunity to respond to editing functions 
pressed while a desk accessory is active. If flag is true, then event was 
handled by desk manager, and no user action is required. Refer to 
Supplied Macforth editor source code for examples. 

TAB.5T0P5 - addr 

Variable containing the number of spaces between tab stops. 

TEACTIVATE 

Refer to Level 2 TE interface documentation. 

TECALTEXT 

Refer to Level 2 TE interface documentation. 

TECLICK 

Refer to Level 2 TE interface documentation. 

TECOPY 

Refer to Level 2 TE interface documentation. 

TECUT 

Refer to Level 2 TE interface documentation. 

TEDEACTIVATE 

Refer to Level 2 TE interface documentation. 
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TEDELETE 

Refer to Level 2 TE interface documentation. 

TEDISPOSE 

Refer to Level 2 TE interface documentation. 

TEIDLE 

Refer to Level 2 TE interface documentation. 

TEIN5ERT 

Refer to Level 2 TE interface documentation. 

TEKEY 

Refer to Level 2 TE interface documentation. 

TENEW 

Refer to Level 2 TE interface documentation. 

TEPASTE 

Refer to Level 2 TE interface documentation. 

TERECORD 

Refer to Level 2 TE interface documentation. 

TE5CR0LL 

Refer to Level 2 TE interface documentation. 

TE5ET.JUST 

Refer to Level 2 TE interface documentation. 

TE5ET.SELECT 

Refer to Level 2 TE interface documentation. 

TE5ETJEXT 

Refer to Level 2 TE interface documentation. 

TE5T.C0NTR0L 

Refer to Level 2 TE interface documentation. 

TEUPDATE 

Refer to Level 2 TE interface documentation. 
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TEXT.BOX 

Refer to Level 2 TE Interface documentation. 

TEXT.CLICK 

Refer to Level 2 TE interface documentation. 

TEXT.FIELD 

Refer to Level 2 TE interface documentation. 

TEXT.RECORD -n 

Constant bit mask for window attribute which Indicates that a text 
record Is pointed to by refcon. 

TEXTFONT n - 

Selects text font. reserved for system, 1 default for user 
applications. MacFORTH uses ^4 (fixed space) for text editing. 

TEXTMODE tx mode - 

Sets Current text bit transfer mode. Valid modes Include: SRCCOPY 
SRCOR SRCXOR 5RCBIC NOTSRCCOPY NOTSRCOR NOTSRCXOR 
NOTSRCBIC 

TEXT5IZE size - 

Sets text size for current graphport. Max value is 50. MacFORTH 
Windows maintain LINEHEIGHT for scrolling and general text output. If 
you set textsize greater than LINE.HEIGHT you will overwrite data on 
the prior line. 

TEXT5TYLE n - 

Selects text style. Each of the first 7 bits enable a particular text 
enhancement. Bit = BOLD( 1 ) Bit 1 = Ital1c(2) Bit 2 = Underline(4) 
Bit 3 = 0utl1ne(8) Bit 4 = Shadow( 1 6) Bit 5 = Condense(32) Bit 6 = 
Extend(64) Just sum up the appropriate values to get the desired style 

THEN 

Marks the end of a conditional structure. Used within a colon definition 
in the form: IF ... ELSE ... THEN or IF ... THEN The word following 
THEN Is executed after the code for IF or ELSE (If present). The error 
message CONDITIONALS NOT PAIRED Indicates there was no preceding 
IF. 

THIS.CONTROL - addr 

Refer to Level 2 controls documentation. 
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THI5.PART -addr 

Refer to Level 2 controls documentation. 

THRU starting screen^Xending screen* — 

Loads screens between and including the starting and ending screen 
numbers given. 

TIB - addr 

User variable containing the address of the terminal input buffer. 

TICKCOUNT - tick count 
Returns real time clock ticks. 

TO.HEAP handle - 

Returns a handle to the heap manager. 

TOGGLE addrXmask ~ 

Complements the 8-bit value in addr by the bit mask given. 

TOGGLE.CONTROL - n 

Refer to Level 2 controls documentation. 

TOKEN.FOR - token 

Inputs the next word in the input stream and converts it to a token. If 
no token is found, is returned instead. 

TOKEN>ADDR token - addr 

Converts a relocatable token to a physical address. 

TONE duration\volume\frequency * 10 — 

Outputs a tone via the sound generator, duration (0-255) is 1/60ths of 
a second, volume (0-255) is a relative volume, and frequecy is 
hertz* 10. 

TRACE - addr 

Compiler Mode switch. When enabled, the compiler emplaces the token 
(TRACE) into the dictionary prior to every token that would otherwise 
normally be compiled. At run-time, (TRACE) tests the state of DEBUG, 
and if True, displays the stack contents with .5 and the NAME of the 
following token. (See (TRACE), DEBUG, and 7TRACE) TRACE ON 
Enabled trace mode. TRACE OFF Disabled trace mode. 
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TRACE.TOKEN -addr 

REturns the address of the variable containing the token to be compiled 
when the trace switch Is on. See TRACE 

TRACK.CONTROL n 1 \n2 - flag 

Refer to Level 2 controls documentation. 

TRIAD screen* ~ 

Displays the triad containing screen*. The three screens Include 
screen*, beginning with a screen number evenly divided by three. 
Output Is suitable for source text records and can be used to replace 
only updated screens In the master listing. 

TRUE -1 

Constant for boolean true value. 

TRUNK - addr 

User variable containing the task unique address of the task's FORTH 
vocabulary. 

TRY 

Pushes the recovery stack frame into the return stack. See RECOVER , 
ABORT" . 

TYPE addrXcnt ~ 

Outputs a string. Transmits cnt characters beginning at addr to the 
current output device. No action Is taken for cnt less than I . 

UNDERLINE - 04 

Constant bit mask for underline text attribute. 

UNIQUE.MSG - addr 

User Variable containing flag which when true, causes CREATE to Issue 
the warning message: ISN'T UNIQUE when a newly created word name 
field Is not unique within CONTEXT and TRUNK . 

UNL0AD.5CRAP - io result 

Writes the desk scrap to disc under the file name "CLIPBOARD". 

UNLOCK.FILE ** Refer to the File System chapter glossary ^* 
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UNLOCK.HANDLE handle - 

Marks relocatable heap data structure as unlocked. See Apple 
Developer's documentation for further details. Reference: HUnlock 

UNTIL flag - 

Terminates a finite control structure. Within a colon definition, marks 
the end of a BEGIN ... UNTIL loop which will terminate based on the 
value of flag. If flag is true, the loop is terminated and control is 
passed to the word following UNTIL . If flag is false, the loop continues 
and control is passed back to the word following BEGIN . BEGIN ... UNTIL 
loops may be nested freely as long as each BEGIN is paired with an 
UNTIL or WHILE...REPEAT . The error message CONDITIONALS NOT 
PAIRED I may indicate an UNTIL is not paired with a BEGIN . See BEGIN , 
WHILE , and REPEAT . 

UP.BUTTON - n 

Refer to MacFORTH Level 2 controls documentation. 

UPDATE — 

Mark the most recently referenced block buffer as modified. The block 
will subsequently be written to mass storage when its buffer is needed 
for storage of a different block, or when SAVE-BUFFERS or FLUSH is 
executed. 

UPDATE.EVENT -n 

Constant event.code returned by D0.EVENT3 on a update event. 

UPPER addrXcnt - 

Converts lowercase characters to uppercase. Any lowercase ASCII 
alpha characters in the string at addr for cnt bytes are converted to 
uppercase ASCII alpha characters. 

UPPERIEFT ( - ) 

Sets the graphics XYOFFSET to the upper left corner of the current 
window. 

USE - addr 

Variable containing the address of the block buffer to use next. This is 
the least recently written block buffer. 

USE" -- 

Refer to the File System glossary. 
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USER n - 

User variable defining word. Used in the form: n USER <name> which 
creates a user variable <name>. n is the eel] offset within the user 
area where the value of <name> is stored. Execution of <name> leaves 
its absolute User Area storage address. 

VARIABLE -- 

Defining word to create variable definitions. Used in the form: 
VARIABLE <name> to create a dictionary entry for <name> and allot four 
bytes for storage in the parameter field. When <name> is later 
executed, it will place the pfa of <name> on the stack. 

VBAR.BOUNDS wptr - t\l\b\r 

Refer to MacFORTH Level 2 controls documentation. 

VECTOR (xl\y1\x2\y2--) 
Draws a 1 1 ne from X 1 ,Y 1 to X2,Y2. 

VERSION 

Types the current software version number and CSI copyright notice. 
Used in TRIAD and COLD. 

VERSION* - n 

Constant containing the specific version of the software release. 

VIRTUAL — position mode 
See File System glossary. 

VOCABULARY size - 

A defining word to create a new vocabulary. Used in the form: 
VOCABULARY <name> to create (in the CURRENT vocabulary) a dictionary 
entry for <name>, which specifies a new ordered list of word def- 
initions. Subsequent execution of <name> will make it the CONTEXT 
vocabulary. When <name> becomes the CURRENT vocab- ulary (see 
DEFINITIONS), new definitions will be created in that list (vocabulary), 
size represents the desired initial size of the vocabulary. 

Wl wXaddr- 

Stores the 16-bit value w at addr. "w-store" 

W* n1\n2~n3 

Returns the signed 32-bit product of the signed 16-bit numbers n1 and 
n2. "w-star" 
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W, w - 

Emplaces w into the dictionary. Stores the 16-bit value in the 
dictionary at the current dictionary pointer value and increments the 
dictionary pointer by 2. 

W.ATTRIBUTES attributesXwptr - 

Sets window attributes before window is displayed. Valid attributes 
include: CLOSE.BOX NOT.VISIBLE SIZE.BOX SCROLL.UP/DOWN 
SCROLL.LEFT/RIGHT TEXT.RECORD 

W.BEHIND [wptr] or [- 1 ] or [0] - 

Sets window order before window is displayed. Window will be placed 
behind wptr when It is displayed. Indicates the window should be 
placed at the front of the list, -1 indicates the window should be 
placed at the end of the list. 

W.B0UND5 t\l\b\r\wptr - 

Sets bounds rectangle for window before it is displayed. 

W.LINKAGE - addr 

Variable containg the latest pointer to a linked list of windows in 
chronological order. This list is traversed during FORGET to close any 
window which is about to be forgotten. 

W.TITLE $addr\wptr~ 

Sets title for window before window is displayed. 

W.TYPE w.typeNwptr — 

Sets window type for window before it is displayed. 

W/ nl\n2-- quotient 

Divides 32-bit n1 by 16-bit n2 leaving a 16-b1t quotient. This routine 
uses the 68000 signed divide hardware instruc- tion for speed, 
"w-dlvide" 

W/MOD n 1 \n2 — rema1nder\quot1ent 

Divides the 32-b1t signed number nl by the 16-b1t signed number n2, 
leaving the 16-bit remainder and quotient. This routine directly 
utilizes the 68000 signed divide hardware instruction, "w-divide-mod" 

W>FUNC>L n ~ 

Macintosh toolbox function call compiler. Refer to the Advanced Topics 
toolbox interface discussion. 
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W>MT n - 

Macintosh toolbox function call compiler. Refer to the Advanced Topics 
toolbox interface discussion. 

W© addr ~ w 

Return the 16-bit value at addr. The error message "Address Error Trap 
at xxxx" indicates addr is odd. See <W@> "w-fetch" 

WAIT n- 

Stub used to maintian source compatability with later products. 

WAIT MOUSEUP - flag 

Waits for mouse button to come up. Returns false if button is already 
up. 

WATCH - addr 

Returns address of watch cursor array. 

WC0N5TANT n - 

16 bit constant defining word. When later executed, pushes signed 16 
bit value into the stack. 

WHILE flag - 

Marks the beginning of the "true portion" of a finite loop construct. 
Used in a colon definition in the form: 

BEGIN ... WHILE ... REPEAT 
On a true flag, continue execution through to REPEAT , which then 
returns control back to the word following the BEGIN . On a false flag, 
skip to the word following the REPEAT , exiting the control structure. 
The error message CONDITIONALS NOT PAIRED indicates the WHILE 
was not nested within a BEGIN .. REPEAT control structure within the 
current definition. 

WHITE - addr 

Returns address of white pattern. 

WINDOW wptr - 

Selects WPTR for output. 

WLIT - n 

Pushes the next 16 bit value in the interpretation stream into the stack 
and advances the interpreter pointer over it. 
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WMOD n 1 \n2 ~ remainder 

Divides 32-b1t nl by 16-b1t n2 leaving the 16-b1t remainder of the 
division. This routine uses the 68000 signed divide hardware 
Instruction for speed. "v\/-mod" 

WORD char - addr 

Parses a string from the Input stream. Receive characters from the 
Input stream until the non-zero delimiting character is encountered, or 
the input stream is exhausted, ignoring leading delimiters. The 
characters are stored as a packed string with the character count in 
the first position. The actual delimiter encountered (char or null) is 
stored at the end of the text string, but not included in the count. If 
the input stream was exhausted as WORD was executed, a zero length 
string will result. The address left on the stack points to the beginning 
of the string (the count byte), the text is placed within the user area at 
POCKET . An error condition exists if the string length exceeds 255, 
leaving only the last 255 characters available. An unchecked error 
occurs if the char given is 0. 

WORDS 

List the CONTEXT vocabulary starting with the most recent definition. 

WRITE.FIXED addr\rec*\file* - 
See File System glossary. 

WRITE.TEXT addr\cnt\file* -- 
See File System glossary. 

WRITE.VIRTUAL addr\cnt\fi1e addrXfile* -- 
See File System glossary. 

XLATE Xl\y1--x2\y2 

Rotates, scales and translates point XV according to the current 
window XYPIVOT (angle), XYSCALE , and XYOFFSET . If cartesian flag is 
true, Y coordinate Is negated. X2,Y2 are expressed in QuickDraw native 
coordinates relative to the current window. 

XOR nl\n2--n3 

Leave the bitwise excluslve-or of nl and n2. "x-or" 

XY>POINT x\y - point 

Packs X under y Into 32 bit point. Y resides in high order word, x in low 
order. 
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XYAXI5 

Displays a '100 x 100 cross hair at the current screen ori- gin. Positive 
X and y are marked with '+', negative with '-". 

XY0FF5ET x\y - 

Sets the offset to the center of the coordinate system to x dots from 
the right and y dots from the top of the current window. 

XYPIVOT angle - 

Causes all subsequent line and dot coordinates within the current 
window to be pivoted by angle degrees. Shapes are not pivoted. 

XY5CALE XSCALEWSCALE -- 

Causes all points In the current window to be scaled by X & Y. Full 
scale Is 100 100 . To increase the size of the image. Increase the scale 
factors above 1 00%. 

ZER0.5CRAP - 10 result 

Zeroes the desk scrap and Increments SCRAP.COUNTER . 



[ 



Begin execution mode. The text from the input stream is subsequently 
executed. See ] . "left-bracket" 



[COMPILE] — 

Forces compilation of an immediate word. Used In a colon- definition 
In the form: [COMPILE] <name> Forces compilation of the following 
word. This allows compilation of a compiling word when it would 
otherwise be executed, "bracket-compile-bracket" 

1 - 

Begin compilation mode. The text from the input stream is 
subsequently compiled. Seel "right bracket" 

{ - 

Accepts and ignores comments from the input stream until the next 
delimiting right brace. Very similar in usage to ( , but can be used 
when multiple occurrances of parentheses are desired In a comment. 
For example: 

{ XXX ( XXX ) XXXX ( XXX ) xxxx ] 

is a valid comment, "brace" 
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71 QUERV 
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75 AAECTANGLE 
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75 SO 
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76 SCA 
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76 SCAAP. HANDLE 
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SEED 

SELECT 

SELECT. UINDOU 

SEND. BEHIND 

SET.CONTAOL 

SET.CONTAOL.NAX 

SET.CONTAOL. n IN 

SET.CONTAOL.AAHGE 

SET.CUASOA 

SET. EOF 

SET. FENCE 

SET. FILE. INFO 

SET.ITEn$ 

SET.OAIGIN 

SET.AEC.LEN 

SET.STAING 

SET.UTITLE 
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78 SHOU 

78 SHOU. CONTROLS 

78 SHOU. CURSOR 

78 SHOU. PEN 

79 SHOU.UIHDOU 
79 SIGH 

79 SIH 

79 SIZE.BOS 

79 SiZE.UINDOU 

79 SnUOGE 

79 SOUHD.FCB 

79 SP! 

79 SPe 

79 SPACE 

80 SPRCES 
80 SORT 
80 SRCBiC 
80 SRCCOPV 
80 SRCOR 
80 SRCXOR 

80 STRCK. ERROR 

80 START. FLAG 

80 STATE 

80 STRTUS 

80 STILL.DOUH 

80 STRiHGUiOTH 

81 SURP 

81 SVS.FILE 

81 SVS.UINOOU 

81 SVSBEEP 

81 SVSPRRHS 

81 SVSTEn.EDIT 

81 TRB. STOPS 

81 TERCTIURTE 

81 TECRLTEXT 

81 TECLICK 

81 TECOPV 

81 TECUT 

81 TEDERCTIUATE 

82 TEDELETE 



82 TEDISPOSE 

82 TEIDLE 
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82 TEICEV 

82 TENEU 

82 TEPRSTE 

82 TERECORD 
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82 TESET.JUST 
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82 TESET. TEXT 

82 TEST. CONTROL 

82 TEUPDRTE 

83 TEXT. BOX 
83 TEXT. CLICK 
83 TEXT. FIELD 
83 TEXT. RECORD 
83 TEXTFONT 

83 TEXTNODE 
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83 TEXTSTVLE 

83 THEH 

83 THIS. CONTROL 
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84 THRU 

84 TIB 

84 TICKCOUNT 

84 TO.HERP 

84 TOGGLE 

84 TOGGLE. CONTROL 

84 TOKEN. FOR 

84 TOKEN>RDDR 

84 TONE 

84 TRACE 

85 TRRCE. TOKEN 
85 TRACK. CONTROL 
85 TRIRD 

85 TRUE 

85 TRUNK 

85 TRV 
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85 UNDERLINE 

85 UNIQUE.nSG 

85 UNLORD. SCRAP 

85 UNLOCK. FILE 

86 UNLOCK. HANDLE 
86 UNTIL 
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86 UPPER 
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86 USE 
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87 USER 

87 URRIRBLE 

87 UBRR. BOUNDS 

87 UECTOR 

87 UERSION 

87 UERSION* 

87 UIRTUAL 

87 UOCABULRAV 

87 U! 

87 U* 

88 U, 

88 U. ATTRIBUTES 

88 U. BEHIND 

88 U. BOUNDS 

88 U. LINKAGE 

88 U. TITLE 

88 U.TVPE 

88 U/ 

88 u/noD 

88 U>FUNC>L 

89 U>nT 
89 Ue 
89 UAIT 

89 UAIT. HOUSE. UP 

89 UATCH 

89 UCDHSTANT 
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(13) 


+REC.SIZE 


(13) 


+SCR« 


(13) 


>FCB 


(24) 


7BL0CKS.FILE 


(25) 


?EOF 


(26) 


7FILES 


(26) 



Uord 



Pogei 



70PEN 


(26) 


eFILE.HRtlE 


(28) 


ROD. BLOCKS 


(29) 


RLLOCRTE 


(30) 


RPPEND. BLOCKS 


(30) 


RSSIGN 


(31) 


BLOCK 


(32) 


BLOCK-FILE 


(32) 


BUFFER 


(33) 


CLOSE. RLL 


(34) 


COPV 


(36) 


CREATE. BLOCKS. FILE (36) 
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Mass Storage (continued): 






Mprd Page* 


Mord 


Page' 


CREATE. FILE ( 


[37) 


POINT 


(69) 


CURREHT-FILE ( 


:37) 


POSITION. FIXED 


(69) 


CURRENT. POSITION ( 


[37) 


PREU 


(70) 


DELETE 1 


[38) 


R/U 


(71) 


DELETE. BLOCKS 1 


[38) 


RERD. FIXED 


(72) 


DISK { 


[39) 


READ. TEXT 


(73) 


EJECT 


[40 


RERD.UIRTUAL 


(73) 


EttPTV-BUFFERS 1 


[42) 


RENOUE 


(73) 


EXTERNAL 1 


[45) 


RENRtlE 


(73) 


FCB.LEN ( 


[45) 


REUIND 


(74) 


FILE. ERROR. tISGS 


[45) 


SflUE-BUFFERS 


(75) 


FILE.TVPE 


[45) 


SELECT 


(77) 


FIRST 


[46) 


SET. EOF 


(77) 


FLUSH 


[46) 


SET. FILE. INFO 


(78) 


FLUSH. FILE 


[46) 


SET.REC.LEN 


(78) 


FLUSH. UOL 


[46) 


SVS.FILE 


(81) 


FROn. CURRENT 


[47) 


UNLOCK. FILE 


(85) 


FROH.END 


[47) 


UPDATE 


(86) 


FROn. START 


[47) 


USE 


(86) 


GET. EOF 


[48) 


USE" 


(86) 


GET. FILE. INFO 1 


[48) 


UIATUAL 


(87) 


GET. FILE.TVPE 1 


[48) 


UAITE. FIXED 


(90) 


GET. ICON 


[48) 


UAITE.TEXT 


(90) 


GET. PICTURE 


[48) 


UAITE. UIATUAL 


(90) 


GET.REC.LEN 1 


[48) 






ILLEGRL.FILE 1 


[53) 






INCLUDE" 


[54) 






INTERNAL 1 


[55) 






lO-RESULT 1 


[55) 






KILL. 10 


[56) 






LltllT 


[57) 






LOCK. FILE 


[58) 






fIflC. FILES 


[59) 






NACR/U 


[59) 






NEXT.FCB 


[63) 






OFFSET 


[65) 






OPEN 


[66) 






OPEN.RSRC 


[66) 
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UocQbulQPJeo qnd 

Dictionopy Honogeient 



Uord 



£agfi£ 



Mord 



«FIHD 


(05) 


NFA 


(63) 


' 


(06) 


OBJECT. FULL!! 


(65) 


(FIHD) 


(09) 


OBJECT. HANDLE 


(65) 


+FIHD 


(12) 


OBJECT.AOOn 


(65) 


* 


(16) 


PFA 


(68) 


II 
* 


(16) 


AESiZE. OBJECT 


(74) 


-FIHD 


(17) 


AESIZE.UOCAB 


(74) 


-FOUND 


(17) 


SET. FENCE 


(77) 


-LATEST 


(17) 


TAUNK 


(85) 


?flLI6H 


(25) 


UOCABULAAV 


(87) 


ALLOT 


(30) 


u, 


(88) 


APPEND 


(30) 






AXE 


(31) 






6HEAD 


(31) 






c, 


(33) 






CONTEXT 


(36) 






CUAAEHT 


(37) 






DEALLOT 


(37) 






DEFtNiTIOHS 


(38) 






DP 


(40) 






EHPTV 


(42) 






FENCE 


(45) 






FIND 


(45) 






FOAGET 


(47) 






FOATH 


(47) 






HEAE 


(50) 






LATEST 


(57) 






HI Ni nun. OBJECT 


(61) 






niNinun.uocAB 


(61) 
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Cpipilep: 




Mora 


Pqgff* 


!CSP 


(04) 


" 


(04) 


'INTERPRET 


(06) 


( 


(06) 


(;COOEe) 


(08) 


(>CODE) 


(08) 


(UORD) 


(ID 


+LORD 


(12) 


+THRU 


(13) 


~> 


(16) 


; 


(23) 


i 


(23) 


>IN 


(24) 


?L0fiDIH6 


(26) 


RLIT 


(30) 


BLK 


(32) 


COnPILE 


(35) 


COOPILIHG 


(35) 


COHSTflNT 


(36) 


CREATE 


(36) 


DOES> 


(40) 


EXECUTE 


(44) 


FIELD 


(45) 


mnEDIRTE 


(53) 


INTERPRET 


(55) 


LIT 


(57) 


LITERAL 


(57) 


Toolbox Interface 


i. 


Uord 


£age£ 


2U>I1T 


(21) 


FUHOL 


(47) 


FUNOU 


(48) 


L>FUNC>L 


(56) 


NT 


(62) 



Uord 

LORD 

HAKE. TOKEN 

NEU. TOKEN 

HEXT.PTR 

POCKET 

QUIT 

SCRN.FROn 

SnUDGE 

STRTE 

THRU 

TIB 

TOKEN. FOR 

TOKEN>RDDR 

USER 

URRIRBLE 

UCONSTRNT 

ULIT 

UORD 

[ 

[CONPILE] 

] 

{ 



Uord 

nT>u 

OS.TRRP 

U>FUHC>L 

U>nT 



Esgsi 

(58) 
(60) 
(63) 
(63) 
(69) 
(71) 
(76) 
(79) 
(80) 
(84) 
(84) 
(84) 
(84) 
(87) 
(87) 
(89) 
(89) 
(90) 
(91) 
(91) 
(91) 
(91) 



Pogef 

(62) 
(67) 
(88) 
(89) 
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Error HontJIing: 








Uprd 


PflgsIL 


Uor4 


Page 


((ABORT)) 


(07) 


ABOAT 


(29) 


((ERROR)) 


(07) 


ABOAT" 


(29) 


(RBORT") 


(08) 


CSP 


(37) 


(RBORT) 


(08) 


EAAOA 


(43) 


(ERROR") 


(08) 


EAAOA" 


(43) 


(ERROR) 


(08) 


HO.AETAV 


(63) 


(EXCPT) 


(09) 


ON. EAAOA 


(66) 


(ON. ERROR) 


(10) 


AECOUEA 


(73) 


.ABORT 


(18) 


AEG. SET 


(73) 


.FILE. ERROR 


(18) 


AESUHE 


(74) 


.S 


(19) 


AETAV 


(74) 


?conp 


(25) 


TAV 


(85) 


?CSP 


(25) 






?EXEC 


(26) 






?FILE. ERROR 


(26) 






?PAIAS 


(26) 






7STACIC 


(27) 







llenuo ; 



Uord 



Uord 



Pogef 



(NENU. SELECT ION:) 


(09) 


flENU. ENABLE 


(60) 


APPEND.! TENS 


(30) 


NENU. HANDLE 


(60) 


DELETE. OENU 


(38) 


riENU.SELECTION: 


(60) 


DAAU.nENU.BAA 


(41) 


NENUS 


(60) 


HILITE.nENU 


(51) 


NEU.HENU 


(62) 


IN.NENUBAA 


(54) 


OPTIONS.HENU 


(66) 


1 TEH. CHECK 


(55) 


SET.! TENS 


(78) 


1 TEH. ENABLE 


(55) 


svsteh.edit 


(81) 


ITEn.lCON 


(56) 






ITEtl.NAAK 


(56) 






ITEtl.STVLE 


(56) 
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H i ndois : 



Upr4 


Page 


(lOH.flCTIUflTE) 


(06) 


(!OH.UPDHTE) 


(06) 


+H6nR 


(12) 


+OH.fiCTIUfiTE 


(!3) 


+0H. UPDATE 


(13) 


+UBflR 


(H) 


+U. ATTRIBUTES 


(14) 


+U. BEHIND 


(H) 


+U.LiHIC 


(H) 


+U.TVPE 


(H) 


+UBOUNDS 


(M) 


+UCBOUNDS 


(15) 


+UFILE.PTR 


(15) 


+ULI HE. HEIGHT 


(15) 


+UREFCON 


(15) 


+UTITLE 


(15) 


+XVBIAS 


(15) 


+XVOFFSET 


(15) 


+XVPIUOT 


(15) 


+XVPOS 


(16) 


+XVSCALE 


(16) 


>SVS.UINDOU 


(25) 


tIN.COHTAOL 


(26) 


ADD.UINDOU 


(29) 


BRING. TO. FRONT 


(32) 


CHECK. BOX 


(34) 


CLIP>COHTEHT 


(34) 


CLOSE 


(34) 


CLOSE. BOX 


(34) 


CLOSE. UINDOU 


(34) 


DEFAULT. ACT lUATE 


(38) 


DFLT. UINDOU. TAIL 


(39) 


DISCARD.UPDRTES 


(39) 


FIND. CONTROL 


(45) 


FIND. UINDOU 


(46) 


FRONT. UINDOU 


(47) 


GET. UINDOU 


(49) 


HBRR. BOUNDS 


(50) 



Uord 



Eaad 



HIDE. UINDOU 


(50) 


HILITE. UINDOU 


(51) 


IN. CLOSE. BOX 


(53) 


IN. DESKTOP 


(53) 


IN.DRRG.BOX 


(53) 


IN.LOUER. UINDOU 


(54) 


IN. SIZE. BOX 


(54) 


IN. SVS. UINDOU 


(54) 


INUALID.RECT 


(55) 


LINE. HEIGHT 


(57) 


NEU. UINDOU 


(63) 


NO. CLIP 


(63) 


NOT.UISIBLE 


(64) 


ON.RCTIURTE 


(65) 


ON.UPDRTE 


(66) 


SCROLL. LEFT/RIGHT 


(76) 


SCROLL. UP/DOUN 


(76) 


SELECT. UINDOU 


(77) 


SEND. BEHIND 


(77) 


SET.UTITLE 


(78) 


SHOU. CURSOR 


(78) 


SHOU.PEN 


(78) 


SHOU. UINDOU 


(79) 


SIZE. BOX 


(79) 


SIZE. UINDOU 


(79) 


SVS. UINDOU 


(81) 


UBRR. BOUNDS 


(87) 


U. ATTRIBUTES 


(88) 


U. BEHIND 


(88) 


U. BOUNDS 


(88) 


U.LINKRGE 


(88) 


U. TITLE 


(88) 


U.TVPE 


(88) 


UINDOU 


(89) 
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GpQphico; 
Uord 



£age£ 



Uord 



Page! 



IPEHSTfiTE 1 


:04) 


get.texthode 


(49) 


IPOIHT < 


:04) 


GET. TEXTS IZE 


(49) 


IRECT ( 


:04) 


GET.TEXTSTVLE 


(49) 


(LINE. TO) ( 


:o9) 


GET.XVOFFSET 


(49) 


(nouE) ( 


:to) 


GET.XVPIUOT 


(49) 


(nOUE.TO) i 


:io) 


GET.XVSCRLE 


(49) 


(PENSIZE) ( 


:io) 


GINIT 


(49) 


(TEKTSIZE) 1 


[to) 


GL06RL>L0CRL 


(50) 


+CRRTESIflH i 


:i2) 


GRRV 


(50) 


+POINT 1 


[13) 


HIDE. CURSOR 


(50) 


-POINT ( 


[17) 


HIDE. PEN 


(50) 


ePEN 1 


[28) 


IBERU 


(52) 


ePEHSTRTE 1 


[28) 


IN IT. CURSOR 


(54) 


©POINT 1 


[28) 


IHUERT 


(55) 


eRECT ( 


[29) 


ITALIC 


(55) 


RRC 


[30) 


LOCRL>GLOBRL 


(58) 


BRCKPRT 1 


[31) 


LOUER.LEFT 


(59) 


BLRCiC 1 


[32) 


LTGRRV 


(59) 


BOLD 4 


[32) 


riRKE.RECT 


(59) 


CRRTESIRH ( 


[33) 


NRX.X 


(60) 


CENTER ( 


[33) 


ttRX.V 


(60) 


CHRRUIDTH 1 


[33) 


nOUE.TO 


(62) 


CIRCLE 1 


[34) 


HOTPRTBIC 


(64) 


CLERR ( 


[34) 


HOTPRTCOPV 


(64) 


CONDENSED 4 


[35) 


NOTPRTOR 


(64) 


CURSOR 1 


[37) 


NOTPRTXOR 


(64) 


DICGRRV 1 


[40) 


NOTSRCBiC 


(64) 


DOT 


[40) 


NOTSRCCOPV 


(64) 


DRRU.CHRR 


[41) 


NOTSRCOR 


(64) 


DRRU.TO 1 


[41) 


NOTSRCXOR 


(64) 


DRRUSTRIHG 


[41) 


OPEN. PORT 


(66) 


ERRSE.RECT 1 


[43) 


OUTLINE 


(67) 


EXTENDED 


[44) 


OURL 


(67) 


FRRNE 


[47) 


PRINT 


(67) 


GET. CURSOR 


[48) 


PRTBIC 


(68) 


GET. LINE. HEIGHT 


[48) 


PRTCOPV 


(68) 


GET. PIXEL 


[48) 


PRTOR 


(68) 


GET.TEXTFONT 1 


[49) 


PATTERN 


(68) 
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GpQphics (continued): 



Uord 



Uopd 



Eflgfii 



PflTXOR 


(68) 


SHRDOU 


(78) 


PEH.NORnRL 


(68) 


SRCBIC 


(80) 


PEHOODE 


(68) 


SRCCOPV 


(80) 


PEHPflT 


(68) 


SRCOR 


(80) 


PENSI2E 


(68) 


SRCXOR 


(80) 


PLfllH 


(69) 


STRINGUIDTH 


(80) 


PLOT. ICON 


(69) 


TEXTFOHT 


(83) 


POINT>XV 


(69) 


TEXTNODE 


(83) 


POLVGON 


(69) 


TEXTS IZE 


(83) 


PTIHRECT 


(70) 


TEXTSTVLE 


(83) 


RDRRU 


(72) 


UNDERLINE 


(85) 


REAL. FONT? 


(73) 


UPPER. LEFT 


(86) 


RECT 


(73) 


UECTOR 


(87) 


RECTANGLE 


(73) 


URTCH 


(89) 


REGION 


(73) 


UNITE 


(89) 


RnOUE 


(74) 


XLRTE 


(90) 


SCALE 


(76) 


XV>POINT 


(90) 


SCALE>XV 


(76) 


XVRXIS 


(91) 


SCALE>V 


(76) 


XVOFFSET 


(91) 


SCREEN. BITS 


(76) 


XVPIUOT 


(91) 


SET. CURSOR 


(77) 


XVSCRLE 


(91) 


SET. ORIGIN 


(78) 







String Hon ipu lot I on; 



^ord 


Page? 


Uopd 


Page? 


a 


(04) 


cnouE 


(34) 


SflODR 


(06) 


CI10UE> 


(34) 


SLIT 


(06) 


COUNT 


(36) 


(SLIT) 


(07) 


CRLF 


(37) 


(.") 


(07) 


ERRSE 


(43) 


-TEXT 


(17) 


FILL 


(45) 


-TRRILING 


(18) 


URTCH 


(60) 


M 


(18) 


PRO 


(67) 


?UORD 


(27) 


UPPER 


(86) 


BLRNKS 


(32) 
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U^er Interface: 








Uprc^ 


Pag?» 


Uor<J 


Page 


(GET) 


(09) 


STRTUS 


(80) 


>LIST< 


(24) 


STILL.DOUN 


(80) 


?Roon 


(27) 


TRIRD 


(85) 


elHIT 


(28) 


UERSION 


(87) 


enOUSE 


(28) 


UERSIOH« 


(87) 


enOUSE.DN 


(28) 


URIT 


(89) 


enOUSEXV 


(28) 


UORDS 


(90) 


BVE 


(33) 






DIR 


(39) 






DIRECTORV 


(39) 






FOLLOUER 


(46) 






GET 


(48) 






ID. 


(52) 






nOUSE. BUTTON 


(61) 






RELERSE 


(73) 






SHOU 


(78) 







Hachine Interface 




Uord 


Pag?« 


ISR 


(04) 


>JSR 


(24) 


eSR 


(29) 


DEU ICE. CONTROL 


(38) 


DEU ICE. STRTUS 


(39) 


STRRT.FLRG 


(80) 
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Debug: 








Word 


Page* 


Uord 


PS9£ 


(.S) 


(07) 


Roori 


(75) 


(TRACE) 


(10) 


SCR 


(76) 


?TRflCE 


(27) 


SCRATCH 


(76) 


DEBUG 


(38) 


STRCK. ERROR 


(80) 


DEBUG. ONLV 


(38) 


TRACE 


(84) 


DEPTH 


(38) 


TRRCE. TOKEN 


(85) 


HRNDLER 


(50) 


UNIQUE.nSG 


(85) 


INDEX 


(54) 






IHITIRLS 


(54) 






INPUT. NUHBER 


(55) 






INPUT. STRING 


(55) 






LIST 


(57) 






LOUER.CRSE 


(59) 






NEEDED 


(62) 






PRUSE 


(68) 






QUIET 


(71) 






R« 


(71) 







Printer and Seriol •■ 



Uprd 


Page' 


+PR INTER 


(13) 


CONFIGURE. PR INTER 


(35) 


OPEN. DEU ICE 


(66) 


OPEN. PR INTER 


(66) 


PRINT 


(70) 


PRINT. BITS 


(70) 


PRINT.FCB 


(70) 


PR INT. SCREEN 


(70) 


PRINT. UINDOU 


(70) 


PRINTER 


(70) 


PR INTER. ONLV 


(70) 


RST. PR INTER 


(75) 


SETUP. SERIAL 


(78) 
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Event R^lqU^s 








Hord 


Pflg?* 


Word 


Page 


-KEVBOFIRD 


(17) 


KEV.DOUN 


(56) 


7EUEHT 


(26) 


KEV. STROKE 


(56) 


eEUEHT 


(28) 


KEV.UP 


(56) 


ABORT. EUEHT 


(29) 


HOUSE. DOUH 


(61) 


RCTIUflTE.EUEHT 


-(29) 


HOUSE. DOUN. RECORD 


(61) 


APPLE. HEHU 


(30) 


HOUSE. UP 


(61) 


flUTO.KEV 


(31) 


HOUSE. UP. RECORD 


(61) 


COnflRHD.KEV 


(35) 


HOUSE. URS.. 


(62) 


DISK.EUEHT 


(39) 


HETUORK.EUEHT 


(62) 


DO.EUEHTS 


(40) 


HULL. EUENT 


(65) 


DRUR.EUENT 


(41) 


POST.EUEHT 


(70) 


EUEHT.LOOP 


(43) 


UPDRTE. EUENT 


(86) 


EUENT. RECORD 


(44) 


UR IT. HOUSE. UP 


(89) 


EUENT. TABLE 


(44) 






EUEHTS 


(44) 






FLUSH. EUEHTS 


(46) 







Constants: 








Word 


Page* 


Uord 


£a9£ 


"BLKS 


(04) 


1H0UR 


(21) 


"DRTA 


(05) 


2 


(21) 


"n4TH 


(05) 


3 


(21) 


"PICT 


(05) 


4 


(22) 


•TEXT 


(05) 


B/BUF 


(31) 


s 


(05) 


BL 


(32) 


-1 


(16) 


BS 


(32) 


-2 


(16) 


C/L 


(33) 


-3 


(16) 






-4 


(17) 









(19) 






1 


(20) 






12H0URS 


(20) 






IDflV 


(20) 
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Sound ; 



Mpr4 


Eage 


?SOUNO 


(27) 


flPLflV 


(30) 


HUSH 


(51) 


OPEN. SOUND 


(66) 


PLflV 


(69) 


SOUND. FOB 


(79) 


SVSBEEP 


(81) 


TONE 


(84) 



Toolbox; 



Uord 


Pogei 


Uord 


Page 


(TRACK. CONTROL) 


(11) 


PUSH. BUTTON 


(71) 


+TUISRECT 


(H) 


PUT. SCRAP 


(71) 


DISPOSE. CONTROL 


(39) 


RAO 10. BUTTON 


(72) 


DOUN. BUTTON 


(40) 


SCARP. COUNTER 


(76) 


ORRU. CONTROLS 


{^U 


SCRAP. HANDLE 


(76) 


GET. CONTROL 


(48) 


SCARP. LEN 


(76) 


GET.SCRRP 


(48) 


SET. CONTROL 


(77) 


HILITE. CONTROL 


(50) 


SET. CONTROL. HflX 


(77) 


IN. BUTTON 


(53) 


SET. CONTROL. n IN 


(77) 


IN. CHECKBOX 


(53) 


SET. CONTROL. RANGE 


(77) 


IH.THUHB 


(54) 


SET.STAING 


(78) 


KILL. CONTROLS 


(56) 


SHOU. CONTROLS 


(78) 


LORD. SCRAP 


(58) 


SVSPRRHS 


(81) 


HUNGER 


(62) 


TERCTIURTE 


(81) 


HEU. STRING 


(62) 


TECRLTEHT 


(81) 


OFF. CONTROL 


(65) 


TECLICK 


(81) 


OH. CONTROL 


(65) 


TECOPV 


(81) 


PRGE.DOUN 


(67) 


TECUT 


(81) 


PAGE. UP 


(67) 


TEDERCTIUATE 


(81) 
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Too I box (continued): 



Uprd 


Paqe 


TEDELETE 


(82) 


TEDISPOSE 


(82) 


TEIDLE 


(82) 


TE INSERT 


(82) 


TEKEV 


(82) 


TEHEU 


(82) 


TEPflSTE 


(82) 


TERECORD 


(82) 


TESCROLL 


(82) 


TESET.JUST 


(82) 


TESET. SELECT 


(82) 


TESET.TEXT 


(82) 


TEST. CONTROL 


(82) 


TEUPDRTE 


(82) 


TEXT. BOX 


(83) 


TEXT. CLICK 


(83) 


TEXT. FIELD 


(83) 


TEXT. RECORD 


(83) 


THIS. CONTROL 


(83) 


THIS.PRRT 


(84) 


TOGGLE. CONTROL 


(84) 


TRACK. CONTROL 


(85) 


UNLOAD. SCRAP 


(85) 


UP. BUTTON 


(86) 


ZERO.SCRRP 


(91) 


ZERO. SCRAP 


(91) 
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MacFORTH Index 






-A- 


Accessing files 


9-7 thru 9- 14 


Allocation: 




of file space 


9-12 


of memory 


5-23,11-10 


Arrays 


5-21 


Assigning Files 


5-3,9-4 



-B- 



Backup 


1-2,3-13 


Beeper 


11-20 


Blocl<s Files 


9-11 


Creating 


9-11 


Allocation 


9-12 


Accessing Source 


9-13 


Booting MacFORTH 


( see loading MacFORTH ) 


Buffers, block 


3-4 



-c- 



Cartesian Coordinates 


6-4 




Case statement 


Going FORTH 




Catalog of files 


( see Directory ) 




Comments 


Going FORTH 




Compilation 


Going FORTH 




Copy 


3-13 




Create: 






files 


9-6, 9-7 




menus 


7-3 




windows 


4-3,8-2 




Cursor 






modifying 


5-11,11-15 




hide 


5-10 




show 


5-10 




Cutting and Pasting 


3-14,11-16 
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-D- 

Data files 9-6 

Debugging 11-3 
Delete; 

files 9-15 

menus 7-8 

Demos, editing 6-27 

Demos, loading 1 -3 

Directory 9-5 



-E- 



Editor 




entering 


3-4 


exiting 


3-4 


menu 


3-8 


selecting a file 


3-2 


ejecting a disc 


9-15 


Error conditions, default 


12-2 


Error 




Handling, user 


11-6 


messages 


9-3,9-20,12-5 


compiler 


12-3 


interpreter 


12-3 


recovery 


11-6 


summary 


12-5 


wliile loading 


3-11 


Event actions, default 


8-7 


Events list 


8-9 



-F- 



File: 




assignments 


3-3 


blocks files 


9-11 


closing files 


9-14 


data files 


9-6 


errors 


9-3 


I/O result codes 


9-3 


numbers 


9-4 


opening files 
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position modes 


9-16 


program files 


See File: blocks files 


reading/writing data 


9-7,9-9 


volumes 


9-4,9-15 


Fixed files 


9-8 


Fonts, Character 


6-14 


Forgetting windows 


5-7 



-G- 
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Hotline 



-H- 

1-5 



-I 



IF statement 


Going FORTH 


Including a File 


9-14 


Input 




from keyboard 


5-15 
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5-15 


string 


5-16 
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11-3 


I/O result codes 


9-3 


Item execution 


7-6 
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-L- 



Levels 1,2,3 


11-7 


Licensing Information 
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6-8, 6-23 
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6-18 


Listing programs 


3-12 


Loading blocks 


3-11 


Loading MacFORTH 


1-2 
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11-5 



-M- 



MacFORTH environment 


11-9 
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11-10 


Memory Maps 


11-11 


Menu 
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7-8 
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7-9 
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example 
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7-6 
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7-7 
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9-15 
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-N- 



-0- 
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6-9 thru 6-13 
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9-15 
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4-8,10-3 
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-R- 
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Scaling coordinates 6-24 

Scroll 3-6 

Selecting a File 3-2 

Shapes 6-20 

Sound 5-20,11-19 

Special characters 7-5 

Storage map 11-11 
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-T- 



Text: 
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6-14 


Files 


9-9 


Mode 
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Output 
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Size 


6-18 


Style 


6-15 


Timer 


11-2 
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Trig functions 


6-25 
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-u- 



-V- 



Vlrtual files 9-11 
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WHILE statement 
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assigning a program to 


5-17 




attributes 


5-8, 8-3 




bounds 


5-10,8-3 




closing a window 


5-9 




event handling 


8-4 




example 


4-3,8-6 
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8-2 




forgetting 


5-7 
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5-19 




hiding a window 
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program 
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show 
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sizing 
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title 
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tracking the mouse 
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